Skip to content

Latest commit

 

History

History
49 lines (36 loc) · 2.02 KB

API.adoc

File metadata and controls

49 lines (36 loc) · 2.02 KB
Raw

Versioning of Narayna LRA REST API

The goal of this document is summarize the approach to REST API versioning in Narayana LRA coordinator service. This document is written for developer of Narayana LRA services.

The version format is major.minor[-preRelease]. The major and minor parts are required and -preRelease is used during development and is optional.

Note
 Any final minor.major release is considered higher than the same version with -preRelease part.

Client may demand behaviour based on particular API version by providing HTTP header Narayana-LRA-API-version on the call.

API definition as Open API document

The Narayana LRA API is documented with Open API annotations at the java classes. The Open API definition needs to be published at the http://narayana.io page.

Changes in LRA REST API

The Narayana LRA REST API is expected to support for at least two previous major versions (ie. support is expected in parallel at least of versions 1.x, 2.x and 3.x until the 4.0 is released).

Changes which do not make a trouble for backward compatibility from client perspective (i.e., addition of features or enhancing the API with return types or similar) are considered to bump a minor version. Incompatible changes needs to bump the major version.

Unsupported version errors

When client demands unsupported version from the REST API endpoint the code returns HTTP status 417 EXPECTATION_FAILED`.

On returning the 417 error the API is expected to return the header Narayana-LRA-API-version with the highest supported API version.

For an unsupported version is considered any request to the REST API endpoint which demands (via HTTP header Narayana-LRA-API-version) version higher than the current API version (i.e., the highest version that the API is created for). The unsupported version could be one that is already deprecated and not supported anymore.