Versions Compared

Old Version 18

changes.mady.by.user Dana Bobko

Saved on

compared with

New Version 19

changes.mady.by.user HuabingZhao

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

       

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

Add a required request parameter value without defaultAPI X  

Add a required request parameter value with defaultAPI  
 X
Add a new resource model or typeResource
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 representationResource 
 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 volumeBehavior  
X  
Changes to documented sorting order of data on returned response w/out changes to volumeBehavior  X 

Changes in behavior that do not change the resource model or representationBehavior  
 X 
Deprecate method, but do not change the structure of the resource model or representationBehavior 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.

...

Custom Headers Specification

Header Name

Specification

X-MinorVersion
  • Used to request or communicate a MINOR version back from the client to the server, and from the server back to the client
  • This will be the MINOR version requested by the client, or the MINOR version of the last MAJOR version (if not specified by the client on the request)
  • Clarification: This will always be the MINOR version requested by the client - OR - if the client does not specify, it will default back to the very first MAJOR version of the server. For example, if the server is on 1.1 and the client does not send X-MinorVersion, the API call will default to 1.0 which makes the MINOR version = 0. This lets the client know they are not receiving the latest version, and they will know because X-LatestVersion will notify them. 
  • Contains a single position value (e.g. if the full version is 1.24.5, X-MinorVersion = "24")
  • Is optional for the client on request; however, this header should be provided if the client needs to take advantage of MINOR incremented version functionality
  • Is mandatory for the server on response
X-PatchVersion
  • Used only to communicate a PATCH version in a response for troubleshooting purposes only, and will not be provided by the client on request
  • This will be the latest PATCH version of the MINOR requested by the client, or the latest PATCH version of the MAJOR (if not specified by the client on the request)
  • Clarification: This will always be the PATCH version the server is running.
  • Contains a single position value (e.g. if the full version is 1.24.5, X-PatchVersion = "5")
  • Is mandatory for the server on response
X-LatestVersion
  • Used only to communicate an API's latest version
  • Is mandatory for the server on response, and shall include the entire version of the API (e.g. if the full version is 1.24.5, X-LatestVersion = "1.24.5")
  • Used in the response to inform clients that they are not using the latest version of the API

Custom Header Flow Diagrams

...

Working Team Information/Discussion

Working Team Members

NameCompanyEmailPhone NumberTime Zone
Rich Bennett 
AT&T 
   



Dana Bobko*

AT&Tdw2049@att.com(561) 371-7619EST

Sharon Chisholm

AMDOCSsharon.chisholm@amdocs.com 
EST

Chris Donley

Huawei Christopher.Donley@huawei.com 

Gregory Glover

AT&Tgg2147@att.com  (847) 420-8459 
Mark HoAT&T mh574f@att.com  (781) 791-4345EST 

Ramki Krishnan

VMware ramkik@vmware.com 

Andy Mayer 

AT&T am803u@att.com
 
 
EST 

Adolfo Perez-Duran

ARM (OAM)adolfo.perez-duran@oamtechnologies.com 720.560.2659MT

Alexander Vul

Intel alex.vul@intel.com 

Parviz Yegani

Huawei Parviz.Yegani@huawei.com (408) 759-1973PT

HuabingZhao

ZTEmailto:zhao.huabing@zte.com.cn
GMT+8

* 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 Gregory Glover to combine the results of this working team with the Documentation effort (there are intersection points).

  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)

...