| Table of Contents |
|---|
This is a draft proposal for RESTful API Design Specification within ONAP. This draft has not be approved by TSC yet.
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.
- Semantic Versioning http://semver.org/
- The version in the swagger file and URI
The main idea is that there are two kinds of versions:- Major version: The version used in the URI and denotes breaking changes to the API. Internally, a new major version implies creating a new API and the version number is used to route to the correct implementation.
- Minor and Patch versions: These are transparent to the client and used internally for backward-compatible updates. They should be reflected in the swagger files to inform clients about a new functionality or a bug fix.
For example, if the version of a RESTful API of an ONAP component is 1.3.2, the Info Object of swagger file should look like
| Code Block |
|---|
title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: http://swagger.io/terms/
contact:
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.3.2 |
The URI should look like: http://{host}/api/v1/pets
- Version discovery
...
.
...
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
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.
- Semantic Versioning http://semver.org/
- The version in the swagger file and URI
The main idea is that there are two kinds of versions:- Major version: The version used in the URI and denotes breaking changes to the API. Internally, a new major version implies creating a new API and the version number is used to route to the correct implementation.
- Minor and Patch versions: These are transparent to the client and used internally for backward-compatible updates. They should be reflected in the swagger files to inform clients about a new functionality or a bug fix.
For example, if the version of a RESTful API of an ONAP component is 1.3.2, the Info Object of swagger file should look like
| Code Block |
|---|
title: Swagger Sample App
description: This is a sample server Petstore server.
termsOfService: http://swagger.io/terms/
contact:
name: API Support
url: http://www.swagger.io/support
email: support@swagger.io
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
version: 1.3.2 |
The URI should look like: http://{host}/api/v1/pets
- Version discovery
Need to be discussed: Should ONAP adopt a version discovery mechanism like OpenStack? :https://wiki.openstack.org/wiki/VersionDiscovery
HTTP response status codes
...
Swagger code generator https://swagger.io/swagger-codegen/
Maven plugin to generate Swagger documents https://github.com/WASdev/tool.swagger.docgen
...