| 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
...
Multiple tenants support
TBD
...
API Documentation(Swagger)
- All the RESTful API must follow Swagger Specification for API documentation: 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
...
Swagger code generator https://swagger.io/swagger-codegen/
Maven plugin to generate Swagger documents https://github.com/WASdev/tool.swagger.docgen
...