Create Camara-OAS-Sections-Guidelines.md #317
Conversation
|
18/OCT: Fine to me so far |
| + [External Documentation](#ext-doc) | ||
|
|
||
| ## Introduction | ||
| Camara uses OpenAPI Specification (OAS) to describe its APIs. The below guidelines specify the restrictions or conventions to be followed within the OAS yaml by all Camara APIs (referred below simply as APIs). |
There was a problem hiding this comment.
Camara -> CAMARA (multiple occurences)
|
|
||
| ## Conventions | ||
| The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119. | ||
|
|
There was a problem hiding this comment.
Suggest to add a section on the OAS file name which should be the api name in kebab-case.yaml e.g. simple-edge-discovery.yaml
| Title describes the API shortly. The title shall not include the term "API" in it. | ||
|
|
||
| #### Description | ||
| No special restrictions specified in Camara. |
There was a problem hiding this comment.
the description shall include the user documentation for the API.
as well as a copy from the section from the ICM guidelines on the auth flows applicable to the API.
| default: http://localhost:9091 | ||
| description: API root, defined by the service provider, e.g. `api.example.com` or `api.example.com/somepath` | ||
| ``` | ||
| <b>API-Name</b> |
There was a problem hiding this comment.
use as in the example above ?
|
|
||
| </br> | ||
|
|
||
| <b>API-Version </b> </br> |
There was a problem hiding this comment.
use as in the example above ?
|
|
||
| For the below example, the API-name would be location-verification. | ||
| ``` | ||
| /location-verification/v0 |
There was a problem hiding this comment.
make this example use v1 instead of v0 (see next comment)
|
|
||
| <b>API-Version </b> </br> | ||
|
|
||
| API-Version shall be same as the [Version](#version) in the info object. |
There was a problem hiding this comment.
shall be a "v" concatenated with the MAJOR version number of the version field in the info object.
A CAMARA specific exception is that for APIs with version 0.y.z, the both the MAJOR and the MINOR version number are included in the , e.g. simple-edge-discovery/v0.3
There was a problem hiding this comment.
this should probably reference the section on API versioning in the API design guidelines
|
|
||
| ### Paths | ||
| No special restrictions or changes specified in Camara. | ||
|
|
There was a problem hiding this comment.
Will this be added to the end of the API Guidelines where there is a section on the OAS specification ? else this risks to create duplication / divergence
|
|
||
| ``` | ||
| #### Title | ||
| Title describes the API shortly. The title shall not include the term "API" in it. |
There was a problem hiding this comment.
I think "Title" should be the "formal" (or "friendly") name of the API, rather than a free text description. Ideally, this name would also documented by API Backlog, though this table would need to be updated as it is currently sub-project rather than API centric.
"Formal" names will be important for marketing purposes. Whilst we can be sure all implementations will use, for example, the name /number-verification within the path, we cannot be sure that the associated implementation documentation will use the name "Number Verification".
|
The work will continue in PR #441 |
5 participants
What type of PR is this?
Add one of the following kinds:
What this PR does / why we need it:
Creates a new document with guidelines for OAS sections. Will add all the content related to OAS sections which was originally part of API design guidelines doc,
Which issue(s) this PR fixes:
Fixes #306
Does this PR introduce a breaking change?
Special notes for reviewers:
Changelog input
Additional documentation
This section can be blank.