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.
...
- Models (add, list)
- Data (CRUD)
- Queries
Jira Ticket:
Jira | ||||||||
---|---|---|---|---|---|---|---|---|
|
Jira Backlog:
Gerrit Review
https://gerrit.nordix.org/#/c/onap/ccsdk/features/+/6477/
External Resources
https://jirawiki.onap.org/secure/RapidBoard.jspa?rapidView=223&view=planning.nodetail&selectedIssue=CCSDK-2912&issueLimit=100/display/DW/Data+Representation
https://wiki.onap.org/display/DW/Interface+style
Open Issues/Decisions
# | Description | Details | Decisions |
---|---|---|---|
1 | Should the java interface take in one (JSON) 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[1]"
}
Request Parameters:
...
200 – OK – Everything is working
|
| ||
2 | Input streams and/or files to take in large amounts of data like yang models? |
| 03/11/20 Team meeting Niamh, Toine, Rishi, Aditya, Bruno, Phillipe We have decided to use (buffered) input streams. |
3 | API uses (generated) ID's or customer provided names? If names are used should we return IDs at all? | 03/11/20 Team meeting notes - Niamh, Toine, Rishi, Aditya, Bruno, Phillipe
Cons:
Other considerations:
| 04/11/20 Team meeting notes - Niamh, Toine, Rishi, Tony We should not expose internal DB ID for dataspace, module set, module, anchor or fragment. DB ids should be fully encapsulated. Exposure of DB ids to clients limits freedom in the future. We do not want to expose them for the following reasons:
Database technology uplift/swap out will not guarantee that ids will be immutable. Any client that uses DB ids would be broken. I can see this being quite important for ONAP trails going to commercially supported ONAP deployments.
We would like to reserve the right to change database ID's. You eliminate the option that will shuffle the ID's without impacting the client.
If there is a fragment that has restricted properties that can only be set at creation. This fragment will be identified by an xpath and internally by a DB id. An update of this (restricted) attribute will require a delete/create – this will change the DB id, but not the xpath. If a client had cached (or otherwise stored) the DB id, then their use case would be broken
|
4 | Should a user be able to delete a dataspace, module ( (of the same revision), module set? |
| 04/11/20Team meeting notes - Niamh, Toine, Rishi, Tony
|
5 | Should a user be able to update/override (create again) dataspace, module (of the same revision), module set? |
| 04/11/20 Team meeting notes - Niamh, Toine, Rishi, Tony For now we are not going to be idempotent but we may consider it in the future. Need to be document clearly as part of Java API proposal (i.e in this wiki!) |
6 | How should we specify attributes? | 1) can it be done by xpaths 2) additional parameters 3) part of query builder? | 11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We will use an optional parameter (suggested name outputSpecification) to specify the leaf(s) (attributes). All queries will return DataNode(s). If you do not specify leaf(s), all leaves will be returned. |
7 | Should we have one method with any type of paths to handle both direct gets with a fully qualified paths(pointing to one unique DataNode) and any type of more advanced paths expression/querys (pointing to multiple DataNodes)? Theoretically this is possible but if might be confusing for the end user | alternative we could have more specialized methods like getDataNode(String cpsPath) queryDataNodes(String cpsPathQuery) And we could still consider an path builder pattern (like a query builder) PathBuilder.withChildOfType() PathBuilder.withAttributeValue() | 11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We decided to use key instead of ID. We have decided to split the behavior into different methods e.g getDataNode(String cpsPath) queryDataNodes(String cpsPathQuery) We do intend to use a query builder too and it will be extended in step with any progress on the xpath query supported functionality |
8 | Will we have separate methods to validate our modules or data? Alternatively validate on submitting of data/modules (and throw validation exception if needed) | 11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We intend to publish validation in a separate java library. We will do validation on write to ensure whatever is being stored in the database is valid and will give the user a fast failure. We will not have separate validation methods on the main Java API. | |
9 | The parser has detailed exception classes instead of one exception with different messages, we need to ask ourselves if we want to have a similar pattern | See section on error handling. | 11/11/20 Team meeting notes - Niamh, Toine, Aditya, Tony, Ruslan, Claudio We intend to have our own detailed validation list of validation exception classes. We will have an exception class hierarchy like below:
|
10 | Order of parameters | When applicable the following order should be applied
| |
11 | Responsibility of module sets will be clarified in a meeting | Options are:
|
|
Error Handling
Exception Class Hierarchy:
- CPSValidationException
- ModelValidationException
- SpecificException1
- SpecificException2
- DataValidationException
- SpecificException3
- SpecificException4
- PathValidationException
- SpecificException5
- ModelValidationException
Expand | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Interface Proposal
can be found at : Interface Proposal for CPS
Proposed grouping of interface methods:
Interface Name | Interface Capabilities |
---|---|
ModuleStoreService |
|
CpsAdminService |
|
DataService |
|
|
|
Java Doc
View file | ||||
---|---|---|---|---|
|
Example Response
...
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"
}
Request Parameters:
...
200 – OK – Everything is working
Example Response
...
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 tree. A anchor must exist before creating a model instance
...
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
...