Versions Compared

Old Version 32

changes.mady.by.user Dana Bobko

Saved on

compared with

New Version 33

changes.mady.by.user Chris Donley

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
Executive Summary

...

Spec ID

Specification/RequirementSpe

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

SG-4

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. 
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

      • required - boolean
      • type - string

...

Item

What

Notes

1

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).
2 R4 and Beyond 

Establish/finalize a proposal for backwards compatibility (BWC) and exposing API versions.

  • BWC would come after all the APIs are "speaking the same language" in how versions are characterized. Once that occurs, we can look to how those API versions are exposed to clients/within interfaces.
  • Dana Bobko has a proposal in her deck that talks about custom headers, but that is just one of many ways this could be done - plus, we need to consider if that will work for every API.
3 Noteworthy 

Dana Bobko will be working with gg2147@att.com to combine the results of this working team with the Documentation effort (there are intersection points).

4Open issueHow do we deal with restconf interfaces (e.g. ODL-based components)? See Dan's comment
  1. REST APIs Must be Hypertext-Driven: Blog post where Roy Fielding argues that not any HTTP-based interface is a REST API
  2. RESTful API Design Specification (for ONAP)
  3. REST APIs don’t need a versioning strategy – they need a change strategy