[jbossts-issues] [JBoss JIRA] (JBTM-3294) Include a custom HTTP LRA version header on REST calls made by our implementation

[Ondrej Chaloupka (Jira)]

    [ https://issues.redhat.com/browse/JBTM-3294?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14107124#comment-14107124 ] 

Ondrej Chaloupka edited comment on JBTM-3294 at 5/20/20 10:08 AM:
------------------------------------------------------------------

We've discussed the aspects of the REST api versioning related to LRA concept within the team.
For the version will be used a custom header with version in format {{<major>.<minor>}}. Where we expect for a breaking change having a new {{<major>}} version. {{<minor>}} version is to be used for addition and other API changes which does not make compatibility issue.
There should be supported at least three versions (the new and the old ones) of API in parallel.

The api will be documented with Swagger/OpenAPI (as it already is) and we should find a proper place where to place the API description (probably at http://narayana.io)



was (Author: ochaloup):
We've discussed the aspects of the REST api versioning related to LRA concept in the team.
For the version will be used a custom header with version in format {{<major>.<minor>}}. Where we expect for a breaking change having a new {{<major>}} version. {{<minor>}} version is to be used for addition and other API changes which does not make compatibility issue.
There should be supported at least three versions (the new and the old ones) of API in parallel.

The api will be documented with Swagger/OpenAPI (as it already is) and we should find a proper place where to place the API description (probably at http://narayana.io)


> Include a custom HTTP LRA version header on REST calls made by our implementation
> ---------------------------------------------------------------------------------
>
>                 Key: JBTM-3294
>                 URL: https://issues.redhat.com/browse/JBTM-3294
>             Project: JBoss Transaction Manager
>          Issue Type: Enhancement
>          Components: LRA
>    Affects Versions: 5.10.4.Final
>            Reporter: Michael Musgrove
>            Assignee: Ondrej Chaloupka
>            Priority: Blocker
>
> Our implementation of the LRA specification exposes REST endpoints whose semantics may change over time. As the LRA spec evolves users will need a guarantee that the endpoints behave consistently.
> To avoid introducing breaking changes I propose that we version REST API calls made by the implementation using a version header, something like:
> bq. OpenStack-API-Version: narayana LRA 5.10.5.Final
> or
> bq. OpenStack-API-Version: narayana LRA 5.10.5.Final https://<the location of our OpenAPI document>
> I went for the [OpenStack guideline|https://specs.openstack.org/openstack/api-wg/guidelines/headers.html] since it was the only standard I could find for custom headers.
> A reason it is narayana specific is that our API offers more than the spec requires.



--
This message was sent by Atlassian Jira
(v7.13.8#713008)