...
# | 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
...
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
...
Description
Read all modules in the store.
Request Parameters:
...
200 – OK – Everything is working
...
Description
Delete a dataspace.
Request Parameters:
...
204 – OK – The resource was successfully deleted
...
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
...
Description
Read an anchor and the associated attributes given a anchor and a dataspace.
Request Parameters:
...
200 – OK – Everything is working
...
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
...
Description
Read all anchors in the given a dataspace.
Request Parameters:
...
200 – OK – Everything is working
...
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
| Code Block |
|---|
[
"container": {
"@name": "bookstore",
"list": {
"@name": "categories",
"key": {
"@value": "name"
}
] |
CPS provides the following interfaces:
Interface Name | Interface Definition | Interface Capabilities | Consumed Models |
|---|---|---|---|
| Model Interface | Behavior interface that provides the capability to access cps modules. |
| Yang models that are broken into fragments. |
| Data Interface | Behavior interface that represents CPS data. |
| |
| Query Interface | Provides the capability to query CPS data. |
|
...
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"]"
}
Request Parameters:
...
200 – OK – Everything is working
Example Response
| Code Block |
|---|
"container": {
"@name": "bookstore",
"list": {
"@name": "categories",
"key": {
"@value": "name"
},
"leaf": {
"@name": "name",
"type": {
"@name": "string"
}
},
"list": {
"@name": "books",
"key": {
"@value": "title"
},
"leaf": [
{
"@name": "title",
"type": {
"@name": "string"
}
},
{
"@name": "lang",
"type": {
"@name": "string"
}
},
{
"@name": "pub_year",
"type": {
"@name": "year"
}
},
{
"@name": "price",
"type": {
"@name": "uint64"
}
}
],
"leaf-list": {
"@name": "authors",
"type": {
"@name": "string"
}
}
}
} |
...
| Code Block |
|---|
module bookstore {
yang-version 1.1;
namespace "org:onap:ccsdk:sample";
prefix book-store;
revision "2020-09-15" {
description
"Sample Model";
}
typedef year {
type uint16 {
range "1000..9999";
}
}
container bookstore {
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;
}
}
}
}
}
|
Schema definitions
TODO
...
Description:
A dataspace is an object that contains yang modules.
...
Description:
An anchor is an object used the describe the base of the model tree. A anchor must exist before creating a model instance
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
...