...
ONAP CVS Proposal Deck was presented to the Architecture Committee on 4/3/2018, prompting the formation of this working team.
Clarification on terminology used for discussion(s):
...
Working Team Members
Name | Company | Phone Number | TIme Time Zone | |
---|---|---|---|---|
AT&T | dw2049@att.com | (561) 371-7619 | ESTEST | |
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 |
What
Notes
...
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
...
- RESTful API Design Specification (for ONAP)