Page Comparison

Important Disclosures and Information

• This page will host the collaborative efforts of the ONAP API CVS proposal working team. The working team's purpose is to devise a consistent API versioning strategy for ONAP.

• The intent of this page is to capture as much information as possible that occurred during working team discussion(s). It does not mean guidance or a solution has been finalized.

• The artifacts/meeting notes contained on this page should not be considered to be the "official" API versioning standard for ONAP, but rather it is the detail of the collaboration taking place amongst the working team.

ONAP CVS Proposal Deck was presented to the Architecture Committee on 4/3/2018, prompting the formation of this working team.

Working Team Members

...

...

...

...

...

...

...

...

...

...

* Responsible team lead

Discussion Items

...

Item

...

What

...

Notes

...

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

...

...

Detail of Proposal Items (Under Review)

Table of Contents

Executive Summary

General objectives of the ONAP Common Versioning Strategy (CVS) for all APIs:

• Implement semantic versioning (MAJOR.MINOR.PATCH) for APIs
• If necessary, refactor APIs to support the concept of MINOR releases; versioning scope and use cases provided
• Adopt a BWC policy for APIs that is current MAJOR release minus 1 year

HTTP/REST API specific rules/policies:

• Implement pre-defined custom headers to communicate MINOR, PATCH, and LATEST VERSION
• Align URLs to include only the MAJOR version
• Documentation using Swagger 2.0, by following the guidance provided

ONAP CVS Proposal Deck was presented to the Architecture Committee on 4/3/2018, and modified on 4/11/2018 to correct the flow diagrams and case of the custom header names.

Clarification on terminology:

• SHALL (mandatory)is used to indicate a requirement that is contractually binding, meaning it must be implemented, and its implementation verified.
• SHOULD (non-mandatory) is used to indicate a goal which must be addressed by the design team, but is not formally verified.

URL Structure Policy

• The URL shall only contain the MAJOR version number to minimize changes in the URL for MINOR and PATCH releases, assuming MINOR.PATCH releases are BWC. 
• The structure of the URL shall be as follows, where version is placed after the "service" or API name:

…/root/{service or API name}/v{version number}/{resource path}

...

Policies for All APIs 

Implementing Semantic Versioning for APIs

• Utilizes the same semantic versioning methodology that is being used for ONAP’s Release Versioning Strategy; therefore, development teams are familiar with the definition of the methodology.
• For a given a version number, MAJOR.MINOR.PATCH, increment the:
  • MAJOR position when you make any incompatible API or component change
  • MINOR position when you add functionality in a backwards-compatible manner
  • PATCH (or BUILD) position when you make invisible (and thus backwards-compatible) bug fixes
• Details of the specification can be found at http://semver.org/

Versioning Scope and Use Cases

Definition of Layers (second column in the table below)

• API-wide - versioning at this level creates a new set of URIs to identify the resources
• Resource-wide - independently version different parts of the API's resource model; major change to a specific resource model with the notion that not all the resource models will change (namespace changes, add a new resource)
• Representation layer - modify and enhance the format, structure or content of resources that are served by the API without changing the resource model
• Behavior change - changes in behavior that do not change the resource model or representation; can include changes in process or state management

...

₁ PATCH refers to the position in the version number, not the HTTP method of PATCH. This method should not be used as it is idempotent.

Backward Compatibility (BWC) Policy

• API BWC shall be defined for MAJOR releases as the current release - 1 year. In other words, if an API is currently at 1.12 and a MAJOR release occurs to increment the version to 2.0, 1.12 (which is BWC for versions 1.0-1.11) must be functional/available for the period of 1 year after 2.0 is released.
• API owners shall ensure the previous MAJOR release remains available and functioning, in its last available production state, for the period of the BWC policy.
• MINOR releases shall be not time or release-based, as they are assumed to be BWC.
• API owners shall ensure no end-to-end services break with the deprecation of an API, due to the BWC Policy. End-to-end services includes, but is not limited to, VNFs, PNFs, Networks, Allotted Resources, etc.

Image Added

Policies for HTTP/REST APIs

API Custom Headers and Behavior

Custom Headers and General Rules

• Three custom headers shall support versioning in APIs:
  • X-MinorVersion
  • X-PatchVersion
  • X-LatestVersion
• The request from the client shall not break, if the headers are absent in the request.
• The server shall employ logic to fallback to the MAJOR version of the API, in the event that X-MinorVersion is not provided.
• Clients shall ignore additional values from the payload in the response, if provided.
  • It shall be explicitly specified in the interface contract that a server may increment a MINOR version and add additional fields.
  • The client shall be capable of handling this type of change in contract, if they remain on a previous MINOR version.

Image Added 

Custom Headers Specification

Custom Header Flow Diagrams

Image Added

URL Structure Policy

• The URL shall only contain the MAJOR version number to minimize changes in the URL for MINOR and PATCH releases, assuming MINOR.PATCH releases are BWC. 
• The structure of the URL shall be as follows, where version is placed after the "service" or API name:

…/root/{service or API name}/v{version number}/{resource path}

Example: {hostname}/aai/resource/v14/complexes

*Note: "v" should precede the MAJOR version number in the URL. Service or API name is not the resource; it is intended to group of set of related resources.

Requirements/Extensions of the Swagger 2.0 Specification

Next Working Team Call

...

Working Team Information/Discussion

Working Team Members

* Responsible team lead

Discussion Items

Resources/Related Links

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)

...