Page History

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)

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 owns the API.

Under the Path, the following shall be required:

x-interface info - this 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 SG-2 above. 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. 

Within the Path Item Object, the following are included in the Swagger specification and shall be required: 

description - string

parameters

• • • required - boolean
    • type - string

R3 Focus/Scope

Establish/finalize a proposal for a generic versioning methodology, URL structure for HTTP/REST APIs, and Swagger 2.0/OpenAPI 3.0 guidance.

• The items in this scope are low hanging fruit that could be achievable for Casablanca; assess doability after the proposal is put forth in the community.
• If one of the identified scope items for R3 cannot be achieved, it is assumed it will move into R4.
• Dana will pull out all relevant items in her deck and park on this page below for the team to review.
• The definition of MAJOR.MINOR.PATCH for the Semantic Versioning 2.0.0 specification is very explicit; we should not deviate from the definitions in the specification (like re-purposing the positions to hold another value).

Current recommendations (on the table):

• Utilize the semantic versioning methodology for APIs (MAJOR.MINOR.PATCH); same definition of the methodology being used for ONAP releases.
• Provide use cases as guidance for incrementing version numbers (see below).
• Provide URL structure policy (see below).
• Provide requirements/extensions of the Swagger 2.0/OpenAPI specification (see below).