| Table of Contents |
|---|
Introduction
Although the PoC will only implement a few of the possible Java API methods it is important to have a good detailed view of the structure and naming of this interface going forward and document it.
...
Open Issues/Decisions
# | Description | Details | Decisions |
|---|---|---|---|
| Should the java interface take in objects(like REST interface) or a few individual fields in a signature? |
API Overview
Description of Operations for Modelling Storage
...
GET /dataspaces/{dataspace-id}/nodes | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
Description Get a node (under any anchor) given a Xpath expression for the given dataspace Get all the relevant nodes given a schema node identifier for the given dataspace | ||||||||||
Request Body { xpath: { xpath specification }} | ||||||||||
Request Parameters:
| ||||||||||
200 OK |
Payload Data Structures
Schema definitions
| dataspace : object |
|---|
Description: A dataspace is an object that contains yang modules. |
...
| Namespace : object |
|---|
Description: A namespace is declared by the yang module. |
Security on the API
Response Codes
The API specification should describe the right HTTP status code to return the client.
Status codes should align with IETF's HTTP Status Code Registry: https://www.ietf.org/assignments/http-status-codes/http-status-codes.xml
For example:
200 – OK – Everything is working
201 – OK – New resource has been created
204 – OK – The resource was successfully deleted
304 – Not Modified – The client can use cached data
400 – Bad Request – The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g., "The JSON is not valid“
401 – Unauthorized – The request requires a user authentication
403 – Forbidden – The server understood the request but is refusing it or the access is not allowed.
404 – Not found – There is no resource behind the URI.
409 – Conflict – Whenever a resource conflict would be caused by fulfilling the request. E.g., Duplicate entries, deleting root objects when cascade-delete not supported, etc.
422 – Unprocessable Entity – Should be used if the server cannot process the entity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
500 – Internal Server Error – API developers should avoid this error. If an error occurs in the global catch blog, the track trace should be logged and not returned as in the response.
All exceptions should be mapped in an error payload. Here is an example how a JSON payload may look:
{
"message": "Sorry, the requested resource does not exist",
"code": 34
}
Rate Limits and Thresholds
e.g Requests per unit time allowed; pagination