ONAP API Common Versioning Strategy (CVS) Proposal

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.

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.

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.

Custom Headers Specification

Custom Header Flow Diagrams

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

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)