Info Section
API Title
The API title specified by the info.title field MUST be present and a non-empty string.
The API title should be descriptive and reflect the purpose of the API.
API Description
The info.description field provides a short overview of the API and MUST be present and a non-empty string.
The API Description should be used to provide the purpose of the API as well as how and why it should be used.
The API Description may include information about basic instructions (e.g., Getting Started) to users on how to use the API, such as host port, authentication, common error codes, test environment, etc., as well as links to additional resources (such as ONAP Use Cases), plus other details that would help other developers start using the API.
The API Description should provide some basic instructions to users on how to use a Swagger viewer (e.g., Redoc, Swagger UI, etc.).
The API Description may be multiline, and GitHub Flavored Markdown, GFM syntax, can be used for rich text representation.
API Contact
The info.contact section provides contact information about the API, including: name, url, and email address.
In ONAP, the info.contact.name field provides the identifying name of the contact organization, and MUST be set to "ONAP"
In ONAP, the info.contact.url field MUST be set to "https://onap.readthedocs.io"
In ONAP, the info.contact.email field MUST be set to "onap-discuss@lists.onap.org"
API License
The info.license section specifies the license name and url for the API.
In ONAP, the info.license.name field MUST be set to "Apache 2.0"
In ONAP, the info.license.url field MUST be set to "http://www.apache.org/licenses/LICENSE-2.0"
API Version
The info.version field is used to provide the version of the application API.
In ONAP, the info.version field MUST be set to the fully-qualified version number of the Swagger file (ex: 1.4.18). Further information about versioning is ONAP may be found at: https://wiki.onap.org/display/DW/ONAP+API+Common+Versioning+Strategy+%28CVS%29+Guidelines
Extension Fields
Within the info section, the following are extensions of the Swagger specification and SHALL be required for ONAP:
The x-planned-retirement-date field MUST use YYYYMM; 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 backwards compatibility for clients.
The x-component field is a string type filed that describes the ONAP component that primarily owns the API from a development perspective. For examples, SDC, MSO, SNIRO, etc., or the mS name.
Host
The host field must specify the host name serving the API. This MUST be the host only and does not include the scheme nor sub-paths. It MAY include a port. (e.g., serverRoot:54321)
Base Path
The basePath field describes base path, relative to the host, on which the API is served. The value MUST start with a leading slash (/). The base path MUST only contain the MAJOR version number to minimize changes in the URL for MINOR and PATCH releases.
For ONAP the basePath field MAY be in the form: "/"<projectName>"/"<apiName>"/v"<majorVersionNumber>
Path Extensions
Under the Path, the x-interface info extension shall be required. This extension contains two attributes:
api-version - fully-qualified version number of the API (ex: 1.3.6); string type. This is the version of the API. This differs from the version in in the Info filed. Components shall follow the Versioning Use Cases above to determine how to evolve API versions.
last-mod-release - use release number or name (this should be consistent, choose either one); string type. This is the last release that the API was modified in.
Path Operations
Operation Id
The operationId field within a path operation MUST be present and non-empty.
The operationId field within a path operation MUST be unique among all operations described in the API.
The operationId field within a path operation SHOULD follow common programming naming conventions.
For ONAP, it is recommended that the operationId field within a path operation be formed as: <objectName>"_"<operation>. (e.g., pets_get)
Operation Summary
The summary field within a path operation MUST be present and non-empty.
The summary field within a path operation should be short, descriptive and reflect the purpose of the operation. Please limit the summary to 5 to 10 words only, and no more than 120 characters.
Operation Description
The description field within a path operation MUST be present and non-empty.
The description field within a path operation should be used to provide the purpose of the operation as well as how and why it should be used, and document any prerequisites and usage specifics.
The description field within a path operation may be multiline, and GitHub Flavored Markdown, GFM syntax, can be used for rich text representation.
The description field within a path operation may provide example calls or usages of the operation.
Operation Tags
The tags field within a path operation MUST be present and non-empty.
Operation must have one and only one tag.
The tags field within a path operation is used to group operations logically into categories or topics, such as Account, Payments, Reports, Search, etc.
Operation Parameters
The description field within an operation parameter MUST be present and non-empty.
Operation Responses
Each Operation must have at least one successful (i.e. 2xx) response defined.
Each Operation should define a default response that covers responses not specifically defined for the Operation.
Models
Examples
All Model Properties that are not $refs should have an example value specified.
Local Definitions
The API specification should not have local definitions (i.e. only $refs are allowed)
That is, APIs should not have the definitions section (even if these local definitions are not used). Instead, schemas should be kept in domains and referenced using domain references.
A domain is a library of common components – such as parameters, responses and data models – that are used across multiple API definitions
Naming Conventions
URL Construction
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. For 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.
A trailing forward slash (/) should not be included in URIs
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
Lowercase letters should be preferred in URI paths
File extensions should not be included in URIs
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
Further Information may be found at: https://wiki.onap.org/display/DW/RESTful+API+Design+Specification
Pluralization of Resource names
Always use plurals in resource / node names to keep API URIs consistent across all operations.
Model Names
Model names should be simple, descriptive, and meaningful.
Model names should be in "upper camel case".
Property Names
Property names should be simple, meaningful, and descriptive with defined semantics.
Property names MUST be camel-cased, ascii strings.
The first character MUST be a letter.
Subsequent characters can be a letter or a digit.
Reserved keywords should be avoided.
Array types should have plural property names. All other property names should be singular.
HTTP response status codes
The API specification should describe the right HTTP status code to return the client.
Status codes should align with IETF's HTTP Status Code Registry: https://www.ietf.org/assignments/http-status-codes/http-status-codes.xml
For example:
200 – OK – Everything is working
201 – OK – New resource has been created
204 – OK – The resource was successfully deleted
304 – Not Modified – The client can use cached data
400 – Bad Request – The request was invalid or cannot be served. The exact error should be explained in the error payload. E.g., "The JSON is not valid“
401 – Unauthorized – The request requires a user authentication
403 – Forbidden – The server understood the request but is refusing it or the access is not allowed.
404 – Not found – There is no resource behind the URI.
409 – Conflict – Whenever a resource conflict would be caused by fulfilling the request. E.g., Duplicate entries, deleting root objects when cascade-delete not supported, etc.
422 – Unprocessable Entity – Should be used if the server cannot process the entity, e.g. if an image cannot be formatted or mandatory fields are missing in the payload.
500 – Internal Server Error – API developers should avoid this error. If an error occurs in the global catch blog, the track trace should be logged and not returned as in the response.
All exceptions should be mapped in an error payload. Here is an example how a JSON payload may look:
{
"message": "Sorry, the requested resource does not exist",
"code": 34
}