Page Comparison

Table of Contents

Executive Summary

...

• Three custom headers shall support versioning in APIs:
  • X-MinorVersion
  • X-PatchVersion
  • X-LatestVersion
• The request from the client shall not break, if the headers are absent in the request.
• The server shall employ logic to fallback to the MAJOR version of the API, in the event that X-MinorVersion 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 add additional fields.
  • The client shall be capable of handling this type of change in contract, if they remain on a previous MINOR version.
• The server shall employ logic to fallback to the MAJOR version of the API, in the event that X-MinorVersion is not provided (see use case below).

Use case for falling back versus failing forward to the MAJOR version of the API

The vserver entity in v1 of ECOMP had no “prov-status” field.
The prov-status field was added in v1.1 as a non breaking change. 

The RO client PUTs all the data in the vserver except the prov-status field, so they use v1.
The GFP client manages the prov-status field in the vserver.  They use v1.1. 

A REST PUT must include the entire representation of the object.
Therefore a v1 PUT does not include the prov-status but the v1.1 PUT must. 

If only major versions get passed, and the system should fail forward, a PUT by RO lacking the prov-status field would wipe out the prov-status value.

Custom Headers Specification

...

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)
3. REST APIs don’t need a versioning strategy – they need a change strategy