ONAP API Common Versioning Strategy (CVS) Proposal Working Team

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

Name	Company	Email	Phone Number	Time Zone
Rich Bennett	AT&T
Dana Bobko*	AT&T	dw2049@att.com	(561) 371-7619	EST
Sharon Chisholm	AMDOCS	sharon.chisholm@amdocs.com		EST
Chris Donley	Huawei	Christopher.Donley@huawei.com
gg2147@att.com	AT&T	gg2147@att.com	(847) 420-8459
Mark Ho	AT&T	mh574f@att.com	(781) 791-4345	EST
Ramki Krishnan	VMware	ramkik@vmware.com
Andy Mayer	AT&T	am803u@att.com		EST
Adolfo Perez-Duran (Deactivated)	ARM (OAM)	adolfo.perez-duran@oamtechnologies.com	720.560.2659	MT
Alex Vul	Intel	alex.vul@intel.com
Parviz Yegani	Huawei	Parviz.Yegani@huawei.com	(408) 759-1973	PT

* Responsible team lead

Discussion Items

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

Detail of Proposal Items (Under Review)

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}

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

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

Use Case	Layer	MAJOR	MINOR	PATCH₁
Refactoring resource model, if it has become fragile or overly complex through many evolutionary steps; introduce a set of namespaces to reflect the category of resources (nothing is where it used to be)	API	X
Restructure resource(s) to meet new business requirements/conform to emerging interface standard(s)	API	X
Add a required request parameter value without default	API	X
Add a required request parameter value with default	API		X
Add a new resource model or type	Resource		X
Update an existing resource model or type w/BWC	Resource		X
Update an existing resource model or type w/out BWC	Resource	X
Adding optional data items to an input resource representation	Resource		X
Add a new behavior method w/no changes to existing behavior methods (e.g. add PUT as a method when it did not exist as prior functionality)	Behavior		X
Changes to data volume on returned response	Behavior		X
Changes to undocumented sorting order of data on returned response w/out changes to volume	Behavior		X
Changes to documented sorting order of data on returned response w/out changes to volume	Behavior	X
Changes in behavior that do not change the resource model or representation	Behavior		X
Deprecate method, but do not change the structure of the resource model or representation	Behavior	X
Adding new optional parameter(s) (that do not change default behavior) to requests	Representation		X
Adding data items to an output resource representation, where any prescribed schema validation (for example, XML Schema or JSON-Schema validation) is not broken	Representation		X
Fix a defect that does not impact behavior or representation (e.g. fix internal algorithm to run more efficiently)	General			X
Changes to error codes, whereas the error code content is updated or changed, with no change in the resource model or representation	API		X

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

Requirements/Extensions of the Swagger Specification

Spec ID	Specification/RequirementSpe
SG-1	All 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

Next Working Team Call

Dana Bobko will setup for week of 4/9/2018.