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 | Phone Number | Time Zone | |
|---|---|---|---|---|
| AT&T | dw2049@att.com | (561) 371-7619 | EST | |
| AMDOCS | sharon.chisholm@amdocs.com | EST | ||
| Huawei | Christopher.Donley@huawei.com | |||
| AT&T | gg2147@att.com | (847) 420-8459 | ||
| Mark Ho | AT&T | mh574f@att.com | (781) 791-4345 | EST |
| VMware | ramkik@vmware.com | |||
| ARM (OAM) | adolfo.perez-duran@oamtechnologies.com | 720.560.2659 | MT | |
| Intel | alex.vul@intel.com | |||
| 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.
Current recommendations (on the table):
|
| 2 | R4 and Beyond | Establish/finalize a proposal for backwards compatibility (BWC) and exposing API versions.
|
| 3 | Noteworthy | Dana Bobko will be working with Gregory Glover 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 | PATCH1 |
|---|---|---|---|---|
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 |
1 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:
|
| SG-5 | Swagger files shall be generated at build time, and be placed in a centralized CodeCloud repository located at: TBD |
| SG-6 | Within the Path Item Object, the following are included in the Swagger specification and shall be required: description - string parameters
|
Next Working Team Call
- Dana Bobko will setup for week of 4/9/2018.
Resources/Related Links
- REST APIs Must be Hypertext-Driven: Blog post where Roy Fielding argues that not any HTTP-based interface is a REST API
- RESTful API Design Specification (for ONAP)