The API Description may be multiline, and GitHub Flavored Markdown, GFM syntax, can be used for rich text representation.
What the API does; Purpose of the API; Who should use the API; Why use the API
For Example: This ONAP Style Sample Rest API provides the requestor with access to snack related information from the ONAP Food component and was originally introduced into ONAP in the Frankfurt Release.
Requirements and use cases, other Interface Specs, Standards, etc.
For Example: This API is build from related standards, including the PopCorn Forum and SNAK.
Short overview of various API components, e.g. envelope and payload design
How to obtain Credentials and access token; Creating accounts; Making REST API Calls (e.g., sandbox vs live) (where); Very simple Try it for yourself (e.g., CURL / Postman sample)
Basic instructions 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. might want to provide some basic instructions to users on how to use Swagger UI.
Quick description of Swagger environment, tools, etc.
Includes summary of information drawn from API definitions in OpenAPI / Swagger files
Includes one-line summaries of each endpoint/resource
Describe the major entities used in the API
If any, describe the appropriate data structures that are included within payload of the API.
Authentication; Authorization; Credentials/access token; etc.
The meaning of Status Codes & Errors
Requests per unit time allowed; Pagination
Describe any behavioral and structural validation constraints
For example, any Pre/Post conditions
Illustrate sequence of client calls to this API, possibly based on Use Cases, presented with diagrams, tables, etc such as:
curl -X GET "https://serverRoot:54321/modeling/sampleApi/v1/snacks/314" -H "accept: application/json;charset=utf-8"
[
{
"id": 314,
"name": "Crunchy Chips",
"tag": "salty"
}
]
Includes:
The version number has major, minor and revision numbers. E.g. v1.0.0 Only the major version number (without the minor number and revision number) is held in the URL. APIs are described with a major version with “v” following the API Name, e.g.: nbi/api/v4/productOrder. The schema associated with a REST API must have its version number aligned with that of the REST API.
The major version number is incremented for an incompatible change. The minor version number is incremented for a compatible change. For minor modifications of the API, version numbering must not be updated, provided the following backward compatibility rules are respected:
For major modifications of the API, not backward compatible and forcing client implementations to be changed, the major version number must be updated.
This operation returns the specific snack from the snack catalog. Attributes category and distributionStatus are available for snack filtering. Fields attribute could be used to filter attributes retrieved
id required | string The id of the snack to retrieve |
Expected response to a valid request
unexpected error