Executive Summary
...
- 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.
...
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). |
| 4 | Open issue | How do we deal with restconf interfaces (e.g. ODL-based components)? See Dan's comment |
...
- 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)
- REST APIs don’t need a versioning strategy – they need a change strategy