...
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
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
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
...