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:

1. Should follow ONAP or wider best practice
2. Documented on ONAP Wiki
3. Discussed and agreed within CPS Team
4. Discussed and agreed with wider community

Currently we are considering 3 'separated' Java APIs or 'groups' of methods:

1. Models (add, list)
2. Data (CRUD)
3. Queries

Jira Ticket:

CCSDK-2871 - Getting issue details... STATUS

Jira Backlog:

https://jira.onap.org/secure/RapidBoard.jspa?rapidView=223&view=planning.nodetail&selectedIssue=CCSDK-2912&issueLimit=100

Open Issues/Decisions

API Overview

Description of Operations for Modelling Storage

Description of Operations for Anchor Persistence

Description of Operations for Node Persistence

[
  "container": {
      "@name": "bookstore",
      "list": {
         "@name": "categories",
         "key": {
            "@value": "name"
         }
]

	"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"
               }
            }
         }
      }

Payload Data Structures

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

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

API Interactions and Flows