Jira Ticket:
| Jira | ||||||
|---|---|---|---|---|---|---|
|
Jira Backlog:
Resources
- https://restfulapi.net/resource-naming/
- https://api.gov.au/standards/national_api_standards/naming-conventions.html
- https://opensource.zalando.com/restful-api-guidelines/
Assumptions
| # | Description |
|---|---|
| 1 | Yang namespaces are globally unique (except for multiple revisions) |
Open Issues/Decisions
API definitions
| Team meeting Flavio,Tony,Toine,Bruno,Niamh, Rishi 8 Oct 2020: The way modules are delivered i.e. grouped in files is not relevant for the CPS application. What needs to be stored for each 'anchor' is the namespace and revision of the model that describes the 'root' of that instance | |||
| Treat operations with xpath and schema_node_identifier as 'queries' using POST? | xpath and schema node identifiers aren't suitable for URLs. The suggestion is to create query URLs instead and pass this data in as part of the request body | Team meeting Niamh Core, Toine Siebelink and Rishi Chail10 Oct 2020 Agreed format, GET nodes resource with query details request body, applied for #11-#13 in the table below |
API definitions
Note 1. This list of URL operations is not meant to be complete or final. It is mainly a starting point to establish a pattern and naming convention for the Configuration Persistence Service.
Note 2. All urls in below table will be prefixed with something like : <server>/api/cps/v1/
Note 3. This does not yet cover authorization.
| Topic AreaGroup | # | Operation | Payload | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
Modelling storage (Create/Read modules) Dataspace is a group (CPS term) | 1 | PUT POST /moduledataspaces/{dataspace-id}/modules | File | Create /Update (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. | ||||||||
| 2 | GET /module/dataspaces/{dataspace-id}/modules | Read all modules in the store .for the given dataspace | ||||||||||
| 3 | GET /moduledataspaces/{namespace} (see assumption #1 and issue #1)dataspace-id}/modules?namespace="namespace-id" | Read all modules in the store for the given dataspace and namespace | ||||||||||
| 4 | GET / moduledataspaces/{ namespacedataspace-id}/ {revision}modules?namespace="namespace-id"&revision="revision" | Read all modules in the store for the given dataspace, namespace and revision | ||||||||||
| 5 | GETDELETE / | moduledataspaces/{dataspace | } (see issue #1)Read all modules in the store for the given dataspace | -id}/ | Delete the given dataspace | |||||||
Anchor persistence (Internal to CPS, associate data relates to a model set to an anchor. Associate data w/ models that give rules when someone queries it). | 6 | POST /dataspaces/{dataspace-id}/anchors | Anchor Points persistence | 6 | PUT /anchor-point/ | Json Object | Create an a new anchor point given a name and a dataspace and module (in the given dataspace (payload includes anchor name, module namespace and revision) | |||||
| 7 | GET /anchor-pointdataspaces/{dataspace-id}/anchors/{nameanchor-id}/ | Read an anchor point and the associated attributes given a name anchor ID and a dataspace. | ||||||||||
| 8 | DELETE /anchor-pointdataspaces/{dataspace-id}/anchors/{nameanchor-id} | Delete an anchor point given a name anchor ID and a dataspace. ( This will delete the whole tree) | ||||||||||
| 9 | GET GET /anchor-pointdataspaces/{dataspace} (see isue#1)-id}/anchors | Read all anchor points anchors in the system given a dataspace. | 10 | GET /module/{dataspace}/{anchor-point}/ | Get a module (reference), given an anchor point | 11 | GET /anchor-point/fragment/{dataspace}/{xpath}/ | Get the anchor point of a fragment given a fragments xpath | ||||
Node persistence (Create/Read of Node Instance Data) Yang Node. | 10 | POST /dataspaces/{dataspace-id}/nodes | Fragment persistence | 12 | PUT /fragment/{dataspace}/{name}/ | File | Create a (root) fragmentnode for a given anchor pointfor the given dataspace, the fragmentnode can have children. Their children will also be persisted as separate nodes in the system. | |||||
| 11 | PUTGET / | fragmentdataspaces/{ | parent-fragmentdataspace-id}/anchors/{anchor-id}/nodes | File | Create a fragment given an ID relative to the parent | Request body: { xpath: { xpath specification }} | Get a node given an anchor for the given dataspace | 14 | GET /fragment/{dataspace}/{name}/ | Get a fragment given a anchor point(return just one level with just xpath references to its children) | ||
| 12 | GET / | fragmentdataspaces/{dataspace-id}/nodes | Request body: { xpath: { xpath specification }} | / (see isue#2)Get a | fragment node (under any anchor) given a Xpath | expression 16expression for the given dataspace | ||||||
| 13 | GET / | fragmentsdataspaces/{dataspace | }/{anchor- | pointid}/ | Get all the fragments under an anchor point given a anchor point (notice similarity with /fragment/{dataspace}/{anchor-point}/ (just one letter!) | nodes | Request body: { schema_node_identifier: { schema_node_identifierspecification }} | 17 | GET /fragment/{dataspace}/schema-node-identifier/{schema-node-identifier}/Get all the relevant | fragments nodes given a schema node identifier | for the given dataspace |
Some thoughts from Toine after discussion with Tony & Flavio
Two possible identifiers for 'anchor points'
...
- &uuid
Tony suggested to just use cps and nothing else to return yang data e..g.
GET <server>/cps/v1?name=xnfproxy&xpath="..." i'm a bit worried that this really looks strange and wrong from REST conventions but I can see why we cannot use the term 'fragment' as that is an application detail. The generic Yang term (as Mark suggested to use Yang terminology) I think is 'Node' or (yang-nodes to prevent confusion with teleccoms nodes)
GET <server>/cps/v1/nodes?name=xnfproxy&xpath="..."
GET <server>/cps/v1/nodes?name=xnfproxy|nodeInAthlone&xpath="..."
GET <server>/cps/v1/dataspaces/{dataspace_id}/anchors → returns Anchor-points
GET <server>/cps/v1/dataspaces/{dataspace_id}/anchors/{anchor-point-id}/nodes?xpath="..." → returns Node(s)
GET <server>/cps/v1/dataspaces/{dataspace_id}/anchors/{anchor-point-id}/nodes?schemaNodeIdentifier="..." → returns Node(s)
GET <server>/cps/v1/dataspaces/{dataspace_id}/nodes&xpath="..." → returns Node(s)
(the same can be used for PUT and DELETE operations)
getting modules seems straight-forward enough:
GET <server>/cps/v1/modules?name=xnfproxy
But not sure what do do to get all the anchor points, maybe
GET <server>/cps/v1/uuids?name=xnfproxy
...