| Table of Contents |
|---|
...
*Note: "v" should precede the MAJOR version number in the URL. Service or API name is not the resource; it is intended to group of set of related resources.
Requirements/Extensions of the Swagger 2.0 Specification
...
Spec ID
...
FOR RESTCONF APIs ONLY
In RESTCONF, APIs are organized by "modules", which for our purposes we can say are analogous to services. There are 3 different types of APIs, each with its own standard URI format:
- Configuration data (also referred to as "config tree"), which stores the in flight view of network data (so it shows pending changes).
- Required URI is /restconf/config/{module}/{resource}
- Operational data (also referred to as the operational tree), which stores the current active view of network data.
- Required URI is /restconf/operational/{module}/{resource}
- RPCs
- Required URI is /restconf/operational/{module}/{rpc name}
URIs for ONAP will follow the convention below:
- Configuration data: /restconf/config/{service}:v{version}_{resource} e.g. /restconf/config/neutron:v2_networks
- Operational tree : /restconf/operational/{service}:v{version}_{resource} e.g. /restconf/operational/neutron:v2_networks
- RPC : /restconf/operations/{service}:v{version}_{rpc} e.g. /restconf/operations/SLI-API:v1_healthcheck
Requirements/Extensions of the Swagger 2.0 Specification
Spec ID | Specification/Requirement |
|---|---|
| SG-1 | All components shall use Swagger 2.0. The specification may be found here. OpenAPI 3.0 is a roadmap item. |
| SG-2 | Within the Info Object, the following annotations are included in the Swagger specification and shall be required, even if they are optional in the Swagger spec: title description version - fully-qualified version number of the Swagger file (ex: 1.4.18) |
| SG-3 | Within the Info Object, the following are extensions of the Swagger specification and shall be required: x-planned-retirement-date - use YYMM; string type. This is the date that the API shall be deprecated, based on the BWC Policy. NOTE: APIs may be active after their retirement date, but are not guaranteed to remain in production. An API retirement may be pushed out to accommodate BWC for clients. x-component - SDC, MSO, SNIRO, etc., or the mS name; string type. This is the component that primarily owns the API from a development perspective. |
| SG-4 | Under the Path, the following shall be required: x-interface info - this contains two attributes:
|
| SG-5 | Swagger files shall be generated at build time, and be placed in a centralized ReadTheDocs repository: http://docs.onap.org |
| SG-6 | Within the Path Item Object, the following are included in the Swagger specification and shall be required: description - string parameters
|
Working Team Information/Discussion
...
- REST APIs Must be Hypertext-Driven: Blog post where Roy Fielding argues that not any HTTP-based interface is a REST API
- RESTful API Design Specification (for ONAP)
- REST APIs don’t need a versioning strategy – they need a change strategy