LRA REST API description

[Jeremy Hughes]

Hi, I'd like to use the LRA Co-ordinator from non-JVM languages. I see http://jbossts.blogspot.com/2017/12/narayana-lra-implementation-of-saga.html has a link to a Javascript client. Is there an OpenAPI description of the full API? Is this API regarded as stable - e.g. from a SemVer perspective breaking changes would cause a bump to the major version.

Many thanks,

Jeremy

[Martin Stefanko]

Hi Jeremy,

just to be clear, the LRA specification does not specify the coordinator API as we want to encourage also non-coordinator based solutions. Narayana is currently the only coordinator based implementation. The Narayana LRA coordinator already contains the annotations for MicroProfile OpenAPI. However, I tried to access it now and it indeed isn't working so I filed https://issues.redhat.com/browse/JBTM-3286. I have a fix ready already so PR will be up after I'll finish this message. After that, you can get the Narayana coordinator OpenAPI definition by running the coordinator (java -jar lra-coordinator/target/lra-coordinator-runner.jar) and then accessing :8080/openapi for OpenAPI document or :8080/swagger-ui for swagger.

On the stability question, I will leave this to someone from the Narayana team. I personally think that the API is now at least for LRA 1.0 stable. However, I can't say if the future change would mean that the Narayana major version would need to be updated.

Martin

[Michael Musgrove]

The REST API is our implementation of the Microprofile LRA specification which is still undergoing change. However I would be surprised if the API underwent radical changes.

The plan would be to keep updating the narayana SNAPSHOT version until version 1.0 of the LRA specification is released after which we will release version 5.x (most likely it will be 5.11) of the narayana. In theory that version of the API will remain stable until there is a new release of the LRA specification which requires it to change (but even then we will endeavour to maintain backwards compatibility).

A non breaking change we could apply is to include a custom HTTP version header and you could check that. If we added that to our next narayana release would that be acceptable?

[Jeremy Hughes]

HI Michael, thanks for the info.

I was more looking for a comment on the REST API of the lra-coordinator. I appreciate that it isn't part of the spec, but since we'd like to describe how to create LRAs that span processes that using a variety of languages. Non-JVM languages would need to rely on the REST API of the coordinator directly rather than through the Java API of MicroProfile LRA which shields the Java programmer from the REST API of the co-ordinator. We could create a client library for each language but it would be easier not to, and to have the programmer call the co-ordinator's REST API in a way of their choosing.

Any thoughts on versioning the API appreciated.

Thanks,

Jeremy

[Jeremy Hughes]

Hi Martin, sorry for my delay in trying this out. I've been 'on vacation' for a few days. I've tried your fix and it works! Thanks so much. btw: ./build.sh install in the root dir didn't build the rts tree for me. I had to go in and do mvn install in there and mvn install in rts/lra too. Maybe I just haven't understood the build process.

This is great, just what I needed. Thanks.

[Michael Musgrove]

In my answer I did say "A non breaking change we could apply is to include a custom HTTP version header and you could check that. If we added that to our next narayana release would that be acceptable?" That was a question for you.

The actual OpenAPI document can be generated by running the coordinator and access the openapi endpoint (curl http://localhost:8080/openapi) but there seemed to be a bug with that so I have generated one for you and I am attaching the resulting document to this post.

[Ondra Chaloupka]

A technical detail about the building of Narayana:

  Running the `./build.sh install` intentionally does not build LRA as it's under development. Once it will be stable I assume it will be built normally.

  Currently for building these parts of Narayana you need to activate the profile `community`, aka. use `./build.sh install -Pcommunity`.

Ondra

[Jeremy Hughes]

Hi, thanks for the info. That makes sense.

[Jeremy Hughes]

Hi Michael, sorry for the late reply. I guess I read too quickly and misunderstood. I think adding a custom HTTP version header would work if there is a convention on backward compatibility. Do you have a plan for that? e.g. similar to Kube's version skew approach, but maybe only necessary to support the new version and one previous in any release of narayana. That way the co-ordinator can be upgraded independently of the participants, but they can't drift far. Another thought would be to provide a version independent of the narayan release because presumably it wouldn't change as frequently.

[Michael Musgrove]

Thanks Jeremy,

These are good suggestions. We are taking various approaches into consideration and we'll propose a solution soon that hopefully solves the issues you raised in the initial post.

--
You received this message because you are subscribed to the Google Groups "narayana-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to narayana-user...@googlegroups.com.
To view this discussion on the web, visit https://groups.google.com/d/msgid/narayana-users/74994c81-4a26-4dff-b473-71e149c76d50%40googlegroups.com.

--

Michael Musgrove

mmus...@redhat.com

JBoss, by Red Hat
Registered Address: Red Hat Ltd, 6700 Cork Airport Business Park, Kinsale Road, Co. Cork.
Registered in the Companies Registration Office, Parnell House, 14 Parnell Square, Dublin 1, Ireland, No.304873
Directors:Michael Cunningham (USA), Vicky Wiseman (USA), Michael O'Neill, Keith Phelan, Matt Parson (USA)

[Ondra Chaloupka]

Hi Jeremy,

we've finally discussed a bit more on the REST API versioning within the Narayana team.

We've agreed that we will use the custom HTTP header for versioning with the <major>.<minor> format independent to Narayana release/

We will be, for sure, supporting at least one previous version in any release but most probably more (like having three parallel versions in any release).

I was assigned to the issue (https://issues.redhat.com/browse/JBTM-3294) so I hope I will get to the review of the swagger documentation and to adding the custom http version header soon.

If you have any idea or a feedback we will be happy to hear it.

Thanks

Ondra

[Jeremy Hughes]

HI Ondra, thanks for this. Some questions inline:

On Wednesday, 20 May 2020 15:08:14 UTC+1, Ondra Chaloupka wrote:

Hi Jeremy,

we've finally discussed a bit more on the REST API versioning within the Narayana team.

We've agreed that we will use the custom HTTP header for versioning with the <major>.<minor> format independent to Narayana release/

This is great. What type of change would bump the major version instead of a minor. Also, would a semantic (rather than syntactic) change bump the minor?

 

We will be, for sure, supporting at least one previous version in any release but most probably more (like having three parallel versions in any release).

 

By 'one previous version' do you mean one major version, one minor version or both combined? Initially I thought you meant both that it doesn't matter whether major or minor change - that change counts as the 'previous'. So in the sequence, 1.0, 1.1, 1.2, 2.0 then 2.0 is compatible with 1.2 (and maybe 1.1 if three parallel versions supported in a release).

I was expecting a the co-ordinator version will need to be >= participant versions. And that an LRA can be between mixed version participants (with the co-ordinator at the highest version).

I was assigned to the issue (https://issues.redhat.com/browse/JBTM-3294) so I hope I will get to the review of the swagger documentation and to adding the custom http version header soon.

Will the http version header apply to participant <-> co-ordinator communications only, or will it be in the service-to-service http call. I'm not sure of a reason this would be needed for now.

[Ondra Chaloupka]

Hi Jeremy. Thanks for your feedback! I haven't got to the task yet but I hope I could start this week while I still owe you response here (sorry, the responses are inline)

On Thursday, May 21, 2020 at 3:47:09 PM UTC+2, Jeremy Hughes wrote:

HI Ondra, thanks for this. Some questions inline:

On Wednesday, 20 May 2020 15:08:14 UTC+1, Ondra Chaloupka wrote:

Hi Jeremy,

we've finally discussed a bit more on the REST API versioning within the Narayana team.

We've agreed that we will use the custom HTTP header for versioning with the <major>.<minor> format independent to Narayana release/

This is great. What type of change would bump the major version instead of a minor. Also, would a semantic (rather than syntactic) change bump the minor?

The current plan is that we would bump the major version in case of the backward compatibility changes we would need to do in future. E.g. if we add a new endpoint for enhancing the feature then bumping the minor version is expected. If we are forced to change the semantics - e.g. type of the output or we found we need to change the use of the HTTP methods then it's a strike to what the client expects and consumes and then we need to bump the major version.

Does this make sense to you?

 

 

We will be, for sure, supporting at least one previous version in any release but most probably more (like having three parallel versions in any release).

 

By 'one previous version' do you mean one major version, one minor version or both combined? Initially I thought you meant both that it doesn't matter whether major or minor change - that change counts as the 'previous'. So in the sequence, 1.0, 1.1, 1.2, 2.0 then 2.0 is compatible with 1.2 (and maybe 1.1 if three parallel versions supported in a release).

When I mentioned both then the I mean both major versions. As we consider the minor version is a version which does not make a trouble for backward compatibility from client perspective then it's mostly about some addition of features or enhancing the api with return types and similar. The changes which impacts the client is expected to be processed as a new major version. There has to be supported in parallel at least versions 1.x, 2.x and 3.x until the 4.0 is released.

I was expecting a the co-ordinator version will need to be >= participant versions. And that an LRA can be between mixed version participants (with the co-ordinator at the highest version).

Yes, the coordinator version needs to be >= participant version but if there is a participant which is too old then coordinator could not be able to correctly communicate. The idea is as mentioned above if the coordinator is in version like 3.1 then the participants are expected to be in versions from 1.0 to 3.1.

 

I was assigned to the issue (https://issues.redhat.com/browse/JBTM-3294) so I hope I will get to the review of the swagger documentation and to adding the custom http version header soon.

Will the http version header apply to participant <-> co-ordinator communications only, or will it be in the service-to-service http call. I'm not sure of a reason this would be needed for now.

What the issue JBTM-3294 discusses and where we start to think about this is the version for participant <-> coordinator. Currently the service-to-service is communication is defined only by LRA specification and there is defined the header with LRA context which needs to be passed among services. For now neither me I can see any reason to add there any version header. I assume the need for it would be driven by the needs in specification than the Narayana implementation (but I am not able to predict here the further development).