Table of Contents

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

Swagger Specification

• All the RESTful API must follow Swagger Specification: http://swagger.io/specification
• The ONAP-Components must provide swagger files for its RESTful API definitions, there are two possible approaches.
  • The developers write the Swagger file, then use CI system to generate the stub codes for implementation.
  • The developers write the Swagger annotation in the source codeI, then use CI system to generate the Swagger file.
• The Swagger file should be placed under the base url of the service so the API definition could be discovered by clients or management tools at runtime. 
  For example, if the base url of peststore service is /api/petstore/v1/, the URL of swagger file should be /api/petstore/v1/Swagger.json

Versioning

API is a public contract between a Server and a Consumer, so it's crucial to make sure the changes are backwards compatible. We need to introduce new versions of the API while still allowing old versions to be accessible when it's necessary. So a versioning mechanism should be considered.

...

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.

...

• 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

HTTP response status codes

The server should always return the right HTTP status code to the client.

...

Need to be discussed: Should ONAP define a unified error response format across projects?

Security

• 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 Authentication
  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 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

...