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.
Acceptance Criteria for Proposed Java Interface:
- Should follow ONAP or wider best practice
- Documented on ONAP Wiki
- Discussed and agreed within CPS Team
- Discussed and agreed with wider community
Currently we are considering 3 'separated' Java APIs or 'groups' of methods:
- Models (add, list)
- Data (CRUD)
- Queries
Jira Ticket:
- CCSDK-2871Getting issue details... STATUS
Jira Backlog:
Open Issues/Decisions
# | Description | Details | Decisions |
---|---|---|---|
1 | 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
POST /dataspaces/{dataspace-name}/modules | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description Create (and validate) a module set (upload a model file) for the given dataspace. Payload is a file containing 1 or more yang modules. This operation will also create a dataspace. | |||||||||||||||
Request Parameters:
| |||||||||||||||
201 – OK – New resource has been created |
GET /dataspaces/{dataspace-name}/modules?namespace="namespace-name"&revision="revision" | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description Read all modules in the store. | ||||||||||||||||||||
Request Parameters:
| ||||||||||||||||||||
200 – OK – Everything is working |
DELETE /dataspaces/{dataspace-name}/ | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Description Delete a dataspace. | ||||||||||
Request Parameters:
| ||||||||||
204 – OK – The resource was successfully deleted |
Description of Operations for Anchor Persistence
POST /dataspaces/{dataspace-name}/anchors | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description Create a new anchor in the given dataspace (payload includes anchor name, module namespace and revision) | |||||||||||||||
Request Body application/json | |||||||||||||||
Request Parameters:
| |||||||||||||||
201 – OK – New resource has been created |
GET /dataspaces/{dataspace-name}/anchors/{anchor-name} | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description Read an anchor and the associated attributes given a anchor and a dataspace. | |||||||||||||||
Request Parameters:
| |||||||||||||||
200 – OK – Everything is working |
DELETE /dataspaces/{dataspace-name}/anchors/{anchor-name} | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description Delete an anchor given a anchor and a dataspace. This will delete the whole tree. | |||||||||||||||
Request Parameters:
| |||||||||||||||
204 – OK – The resource was successfully deleted |
GET /dataspaces/{dataspace-name}/anchors | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
Description Read all anchors in the given a dataspace. | ||||||||||
Request Parameters:
| ||||||||||
200 – OK – Everything is working |
Description of Operations for Node Persistence
POST /dataspaces/{dataspace-name}/nodes | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description Create a (root) node for a given anchor for the given dataspace, the node can have children. Their children will also be persisted as separate nodes in the system. | |||||||||||||||
Request Parameters:
| |||||||||||||||
201 – OK – New resource has been created |
POST /dataspaces/{dataspace-name}/anchors/{anchor-name}/nodes | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Description Get a node given an anchor for the given dataspace (return just one level with just xpath references to its children) | |||||||||||||||
Request Body { "xpath" : "/dataspace/anchors/nodes//module[@xmlns="urn:ietf:params:xml:ns:yang:yin:1"]/container[@name="bookstore"]@name" } | |||||||||||||||
Request Parameters:
| |||||||||||||||
200 – OK – Everything is working | |||||||||||||||
Example Response list books { key title; leaf title { type string; } leaf lang { type string; } leaf-list authors { type string; } leaf pub_year { type year; } leaf price { type uint64; } } |
POST /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" : "/dataspace/anchor/nodes/module[@xmlns="urn:ietf:params:xml:ns:yang:yin:1"]/container[@name="bookstore"]@name" } | ||||||||||
Request Parameters:
| ||||||||||
200 – OK – Everything is working | ||||||||||
Example Response list categories { key name; leaf name { type string; } list books { key title; leaf title { type string; } leaf lang { type string; } leaf-list authors { type string; } leaf pub_year { type year; } leaf price { type uint64; } } } |
Payload Data Structures
Schema definitions
TODO
dataspace : object |
---|
Description: A dataspace is an object that contains yang modules. |
anchor : object |
---|
Description: An anchor is an object used the describe the base of the tree. A anchor must exist before creating a model instance |
Namespace : object |
---|
Description: A namespace is declared by the yang module. |
Security on the API
TODO
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
TODO