Table of Contents

This is a draft proposal for RESTful API Design Specification within ONAP. This draft has not be approved by TSC yet.

...

Need to be discussed: Should ONAP adopt a version discovery mechanism like OpenStack?  :https://wiki.openstack.org/wiki/VersionDiscovery

URI Construction

RESTful APIs use Uniform Resource Identifiers (URIs) to address resources, ONAP projects should comply with a unified URI standard to implement the microservices.

• URI structure
  URI structure http://[host]:[port]/api/{service name}]/v{version number}/{resource}
  The URI is comprised of a fixed base uri /api/{service name}]/v{version number} and the resource path. Only major version number is used in the URI. An example: http://127.0.0.1:8080/api/petstore/v1/pets/dogs

• CRUD function names should not be used in URIs. Instead, CRUD actions should be represented by HTTP methods. Below is the proposed methodology to implement CRUD operations in a RESTful API.

  Resource	POST	GET	PUT	DELETE
  /api/petstore/v1/pets/dogs	Create a new dog	List dogs	Replace dogs with new dogs(Bulk update)	Delete all dogs
  /api/petstore/v1/pets/dogs/bailey	Error	Show dog	If exist update dog else ERROR	Delete dog

  Do not use:

...

A forward slash (/) adds no semantic value and may cause confusion. RESTful API’s should not expect a trailing slash and should not include them in the links that they provide to clients.

• Forward slash separator (/) must be used to indicate a hierarchical relationship
• Use Hyphens (-) instead of Underscores (_)  if separation of words is needed in the URI

 Underscores (_) can be hidden by the underline of URIs in browsers.

• Lowercase letters should be preferred in URI paths

When convenient, lowercase letters are preferred in URI paths since capital letters can sometimes cause problems. RFC 3986 defines URIs as case-sensitive except for the scheme and host components.

• File extensions should not be included in URIs

A REST API should not include artificial file extensions in URIs to indicate the format of a message’s entity body. Instead, they should rely on the media type, as communicated through the Content-Type header, to determine how to process the body’s content. 

• A plural noun should be used for collection names
  For example, the URI for a collection of dog documents uses the plural noun form of its contained resources: /api/petstore/v1/pets/dogs
• A singular noun should be used for document names
  For example, the URI for a single dog document would have the singular form: /api/petstore/v1/pets/dogs/bailey

...

• Token Based Authentication
  Ideally, microservices should be stateless so the service instances can be scaled out easily and the client requests can be routed to multiple independent service providers. A token based authentication mechanism should be used instead of session based authentication 
• API-Token  AuthenticationAuthentication
  ONAP is supposed to be accessed by third-party apps such as OSS/BSS, in the authentication process a user is not involved. API-Token can be used in such cases.
• Centralized Authentication/Authorization
  The MSB API Gateway can serve as the entry point to authenticate client requests and forwards them to the backend services, which might in turn invoke other services.
  MSB doesn't do the authentication itself, instead, MSB can work with a security provider to provide SSO for centralized Authentication or ONAP with its pluggable architecture.Internal Access Control
  

  Need to be discussed: Should ONAP enforce Authentication/Authorization for internal communication between ONAP components? For example, the requests routed via internal API Gateway(Router). 

Multiple tenants support

TBD

Appendix

Maven plugin to generate Swagger documents https://github.com/WASdev/tool.swagger.docgen

Swagger Code Generator https://github.com/swagger-api/swagger-codegen

MSB SSO Centralized Authentication & Authorization solution https://wiki.onap.org/download/attachments/3246982/Capture7.PNG?version=1&modificationDate=1495079131000&api=v2

...