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 (to be re-visited post-Casablanca)

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 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 (to be re-visited post-Casablanca). 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.
• 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.
• The server shall employ logic to fallback to the MAJOR version of the API, in the event that X-MinorVersion is not provided (see use case below).

Use case for falling back versus failing forward to the MAJOR version of the API

The vserver entity in v1 of ECOMP had no “prov-status” field.
The prov-status field was added in v1.1 as a non breaking change.  

The RO client PUTs all the data in the vserver except the prov-status field, so they use v1.
The GFP client manages the prov-status field in the vserver.  They use v1.1.  

A REST PUT must include the entire representation of the object.
Therefore a v1 PUT does not include the prov-status but the v1.1 PUT must.  

If only major versions get passed, and the system should fail forward, a PUT by RO lacking the prov-status field would wipe out the prov-status value.

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)
3. REST APIs don’t need a versioning strategy – they need a change strategy