Resources
- https://restfulapi.net/resource-naming/
- https://api.gov.au/standards/national_api_standards/naming-conventions.html
Assumptions
| # | Description |
|---|---|
| 1 | Yang namespaces are globally unique (except for multiple revisions) |
Open Issues/Decisions
| # | Description | Details | Decisions |
|---|---|---|---|
| 1 | How to differentiatie GET queries with different parameters. If we dont have named parameters how best to know what is meant | Alternatives
| Team meeting Flavio,Tony,Toine,Bruno,Niamh, Rishi 8 Oct 2020: Use hierarchical resource urls including the concept of 'dataspaces' and 'anchors'. 'Fragments' will be replaced by 'Nodes' e.g. GET /dataspaces/{dataspace_id}/anchors → returns Anchor-points GET /dataspaces/{dataspace_id}/anchors/{anchor-id}/nodes?xpath="..." → returns Node(s) GET /dataspaces/{dataspace_id}/anchors/{anchor-id}/nodes?schema_node_identifier="..." → returns Node(s) GET /dataspaces/{dataspace_id}/nodes&xpath="..." → returns Node(s) GET /dataspaces/{dataspace_id}/modules → returns Modules |
| 2 | Advance queries v Simple Queries (gets) for data fragments. Do we want/need differentiatie on UTL? |
Note . The xpath could be a full unambiguous xpath returning one object or it could be partial path using wildcards etc allowing for more advanced queries return 0 or more fragments (developed over many iterations) | Team meeting Flavio,Tony,Toine,Bruno,Niamh, Rishi 8 Oct 2020: Advanced queries will implemented as advanced xpath' (and or schema node identifiers) no need for separate URLs |
| 3 | We have no modules sets! | model files just arbitrarily group a few modules, is there a need to persist this grouping (We do have the concept of a dataspace as well) | 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 |
API definitions
Note. All urls in below table will be prefixed with something like : <server>/cps/v1/
| Group | # | Operation | Payload | Description |
|---|---|---|---|---|
Modelling storage | 1 | PUT /module/{dataspace} | File | Create/Update (and validate) a module set. (upload a model file) |
| 2 | GET /module/ | Read all modules in the store. | ||
| 3 | GET /module/{namespace} | Read all modules in the store for the given namespace | ||
| 4 | GET /module/{namespace}/{revision} | Read all modules in the store for the given namespace and revision | ||
| 5 | GET /dataspaces/{dataspace-id}/modules | Read all modules in the store for the given dataspace | ||
Anchor Points persistence | 6 | PUT /anchor-point/ | Json Object | Create an anchor point given a name and a dataspace and module (namespace and revision) |
| 7 | GET /anchor-point/{dataspace}/{name}/ | Read an anchor point and the associated attributes given a name and a dataspace. | ||
| 8 | DELETE /anchor-point/{dataspace}/{name} | Delete an anchor point given a name and a dataspace. (will delete whole tree) | ||
| 9 | GET /dataspaces/{dataspace-id}/anchors | Read all anchor points 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 node xpath | ||
Fragment persistence | 12 | PUT /fragment/{dataspace}/{name}/ | File | Create a (root) node for a given anchor point, the node can have children. |
| 13 | PUT /fragment/{parent-fragment-id}/ | File | Create a node given an ID relative to the parent | |
| 14 | GET /fragment/{dataspace}/{name}/ | Get a node given an anchor point (return just one level with just xpath references to its children) | ||
| 15 | GET /dataspaces/{dataspace-id}/nodes&xpath="..." | Get a node given a Xpath expression | ||
| 16 | GET /dataspaces/{dataspace_id}/anchors/{anchor-id}/nodes?xpath="..." | Get all the nodes under an anchor point given a anchor point (notice similarity with /fragment/{dataspace}/{anchor-point}/ (just one letter!) | ||
| 17 | GET /dataspaces/{dataspace_id}/anchors/{anchor-id}/nodes schema_node_identifier="..." | Get all the relevant nodes given a schema node identifier (not need to specify dataspace is schema-node-identifier is globally unique) |