Versioning API Documentation Recommendation June 2018 ONAP API

Versioning & API Documentation Recommendation June, 2018 ONAP API Sub-Team Leads Rich Bennett - AT&T Dana Bobko – AT&T Eric Debeau´ - Orange Greg Glover – AT&T (Doc PTL) Andy Mayer – AT&T Jack Pugaczewski – Century. Link Rene´ Robert – Orange Other Contributors (Thank You!) Amdocs ARM (OAM) Ericsson Huawei Intel VMWare ZTE

Versioning & API Documentation policy* * This replaces current offerapis template For each API identify the following: 1. Introduction Provide a brief (one/two line) summary of the API including functionality and scope 2. API Architecture Identify role of API in ONAP architecture, including consumer / producer roles and stakeholders 3. API Version ONAP Wiki: API Common Versioning Strategy For all APIs: • Support semantic versioning (MAJOR. MINOR. PATCH) for APIs • Adopt a backwards compatibility policy. Draft recommendation: MAJOR release minus 1 year (to be reviewed at M 1) In addition for HTTP/REST APIs: • Document using Swagger 2. 0, by following the guidance provided • Align URL to include only the MAJOR version • Assign pre-defined custom headers to communicate MINOR, PATCH, and LATEST VERSION 4. API Description Provide a detailed view of the APIs, including both functional and informational scope 5. API Table Provide links as appropriate: e. g. Json, HTML, Plant. UML, Swagger, Postman Collection, pdf 6. Mapping to ONAP Information Model Identify the associated Information Model Class and Attribute 7. API Security Describe the security mechanism for the API, e. g. , authentication and authorization scheme 8. Developer Guide Provide API technical information including Dependencies, Configuration, Running & Testing 2

Versioning & API Documentation policy Policy recommendation reviewed by: • PTLs – regular weekly calls & targeted calls • Architecture Sub-Team • Versioning working team • API Documentation working team Implementation plan Ø New APIs starting with Casablanca: use new policy and template Ø Existing APIs: use current format 3

Versioning & API Documentation – Implementation Questions Recommendations 1. Are extensions to the API table allowed? Example: AAI proposes down loadable: • HTML - Covered in the proposed template • XSD - Not covered in the proposal • OXM - Not covered in the proposal 1. Yes, as extensions to standard format 2. Where should these release controlled documents be stored/referenced? • RTD download with naming conventions • Nexus. onap. org raw site • Other? 2. RTD with naming conventions 3. Will we differentiate between External and Internal APIs? 4. What about versioning for other ONAP constituents, such as other Declaratives (e. g. VNF Descriptors using TOSCA template), Models, Micro-services, etc. 5. Can we separate establishing a BWC Policy, from the Policy timeframe itself? 3. No. If/when a hierarchy is developed this can be re-addressed 4. Not in scope of this recommendation, will be worked on Versioning subteam 5. Yes. Draft recommendation for timeframe is: MAJOR release minus 1 year, to be reviewed during Casablanca. 4

Versioning & API Documentation API Template Examples 5

API Documentation Example - 2. Architecture 6

API Documentation – 3. Semantic Versioning • Utilizes the same semantic versioning methodology that is being used for ONAP’s Release Versioning Strategy; therefore, development teams are familiar with the definition of the methodology. • For a given a version number, MAJOR. MINOR. PATCH, increment the: - MAJOR position when you make any incompatible API change - MINOR position when you add functionality in a backwards-compatible manner - PATCH (or BUILD) position when you make invisible (and thus backwards-compatible) bug fixes • Details of the specification can be found at http: //semver. org/ 7

API Documentation – 3. Backwards Compatibility Policy • API BWC shall be defined for MAJOR releases. In other words, if an API is currently at 1. 12 and a MAJOR release occurs to increment the version to 2. 0, 1. 12 (which is BWC for versions 1. 0 -1. 11) must be functional/available for the policy period* after 2. 0 is released. • API owners shall ensure the previous MAJOR release remains available and functioning, in its last available production state, for the period of the BWC policy. • MINOR releases shall be not time or release-based, as they are assumed to be BWC. • API owners shall ensure no end-to-end services break with the deprecation of an API, due to the BWC Policy. End-to-end services includes, but is not limited to, VNFs, PNFs, Networks, Allotted Resources, etc. 8

API Documentation – 3. BWC policy period Recommendation: MAJOR release must be functional/available for 1 year after the following MAJOR version is released. For example, if an API is currently at 1. 12 and a MAJOR release occurs to increment the version to 2. 0, 1. 12 (which is BWC for versions 1. 0 -1. 11) must be functional/available for 1 year after 2. 0 is released. Proposed Implementation: • One year policy period will start with development of the Casablanca release (R 3) • BWC Policy will be reviewed by the PTLs and TSC at M 1, and the policy and/or policy period will be adjusted if needed 9

API Documentation – 3. URLs • 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{MAJOR version number}*/{resource path} Example: {hostname}/aai/resource/v 14/complexes *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. 10

API Documentation – 3. Custom Headers and Behavior • Three custom headers shall support versioning in APIs: - X-Minor. Version, - X-Patch. Version, and - X-Latest. Version. • The request from the client shall not break, if the headers are absent in the request. • The server shall employ logic to fallback 1 to the MAJOR version of the API, in the event that XMinor. Version is not provided. • Clients shall ignore additional values from the payload in the response, if provided. - It shall be explicitly specified in the interface contract that a server may increment a MINOR version and additional fields. - The client shall be capable of handling this type of change in contract, if they remain on a previous MINOR version. 11

API Documentation – 3. Custom Headers and Behavior Header Name Specification X-Minor. Version • • • X-Patch. Version • • • X-Latest. Version • • • 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-Minor. Version, 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-Latest. Version will notify them. Contains a single position value (e. g. if the full version is 1. 24. 5, X-Minor. Version = "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 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-Patch. Version = "5") Is mandatory for the server on response 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, XLatest. Version = "1. 24. 5") Used in the response to inform clients that they are not using the latest version of the API 12

API Documentation – 3. Custom Headers and Behavior Comprehensive use cases should be provided on the Wiki so the expectation is set for when a MAJOR. MINOR. PATCH should be incremented. 13

API Documentation – 3. Custom Headers and Behavior 14

API Documentation Example - 4. Description service. Catalog: From TMF 633 service. Catalog API at a glance: Only high level information are provided - swagger is documented. Only service. Specification resource is provided. Information are retrieved in SDC (and in Tosca file) - Only GET operation is provided - this API DID NOT UPDATE SDC Only characteristics at service level will be retrieved in ONAP Tosca file. For example if an ONAP service is composed of VNF and the VF module, the service. Specification resource will only feature characteristic describe in the ONAP service tosca model and not attributes in the tosca files for VNF or VF module. Only ‘basic’ service characteristics will be managed in this release. By ‘basic’ we mean string, boolean, integer parameter type and we do not manage ‘map’ or ‘list parameter type GET service. Specification(list) (example: GET /nbi/api/v 1/service. Specification/? category=Network. Service&distribution. Status =DISTRIBUTED) It is possible to retrieve a list of service. Specification (get by list). Only attributes category and distribution. Status are available for service. Specification filtering. It is possible to select retrieved attributes using fields attribute. if no service. Specification matches, an empty list is send back. GET tservice Specification (id) (example: GET /nbi/api/v 1/service. Specification/{uuid}) It is use to retrieve one service. Specification - all available information are retieved (see swagger for description) 15

API Documentation Example – 5. API Table The “links” in each section of the table should be down loadable, release controlled files Example: http: //onap. readthedocs. io/en/latest/submodules/externalapi/nbi. git/docs/offeredapis/index. html 16

API Documentation Example - 8. Developer Guide 17

Versioning – Open Issues The following will be added to future work list for Versioning sub-team • What Versioning guidelines/standards if any should be adopted for: Ø Declarative Interfaces other than REST API’s (e. g. VNF Descriptors using TOSCA template) Ø Models Ø Micro-Services Ø Other • Should separate Versioning guidelines/standards be adopted for External vs. Internal Interfaces (assuming a hierarchy is established) 18