Starting a spec on type safe REST clients

[John D. Ament]

For some reason, I thought Ken Finnigan had already threw this one out there but I couldn't find a discussion so figuring I'll start one based on the new rules.

In the Microservices world, we typically talk REST to other services.  While the JAX-RS specification defines a fluent API for making calls, it is difficult to make it a true type safe client.  Several JAX-RS implementations support the ability to take an interface definition and create a JAX-RS client from it (JBoss RestEasy, Apache CXF) as well as being supported by a number of service providers (Wildfly Swarm, OpenFeign).  I think its useful for us to standardize on having such a feature set, as well as defining an API to support the creation of the service proxies.  This API would support both CDI and non-CDI approaches.  The API should also provide integration to configurability to support resolving service locations via configuration properties.

Based on the new process, I'm going to leave this open for at least 72 hours.  If I see no -1's I'm going to request repository creation.

John

[Mark Little]

+1 to the general concept but I have a question: in an ideal world would you want to see this as part of JAX-RS or would it always be its own thing?

Mark.

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/2c741142-b471-4c68-8525-c35f9b574ae8%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[sst...@redhat.com]

After not seeing such an addition to the JAX-RS 2.1 update, I went to the new JAX-RS github project and found this open issue:

Standardize proxy-based JAX-RS client API

https://github.com/jax-rs/api/issues/501

It is marked as a major priority issue, but it does not have a target release. We will want to see this standardized in the JAX-RS client api in my view, but we can provide a input for that based on this effort in the interim.

[John D. Ament]

I'll point out that my old java.net username was "genomeprjct" so I can say I'm familiar with that issue (including my misreading of HTTP proxy for java proxy).  There was an email thread (unfortunately no longer archived due to java.net shutdown) that indicated the Oracle side was not interested in pursuing a feature like this, and caused one E.G. member to basically "vent his frustrations" on the lack of progress.  So while I'm hopeful Oracle may reconsider at a later, I feel the only way we can make it happen is based on community interest.

[Mark Little]

Yes my original question was loaded ;) Prior to moving to Eclipse I know we (the MP group) discussed once or twice the issue about driving changing into existing EE specifications and particularly if they were ones not under the direct leadership of a MP member. Whilst this should not be an impediment to the work we want to do here, which should go forward so we can get the real-world experience we continue to push as a clear benefit of not standardising too early, I think this might also be a useful test case.

Mark.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/56cdc5a1-57b0-4fbb-91b5-a023ad9de43c%40googlegroups.com.

[Heiko Rupp]

I think this is a good idea per se, but would like to see this broadened for not-only Java clients.

While we here are all Java aficionados, I believe that the real value of REST (over HTTP) is that basically all systems from Mainframe to Arduino have a way of speaking REST (over HTTP).

I guess the approach should be via OpenAPI/Swagger, where we emphasize on an interface exchange format (No, Mark not Corba IDL :-)  and then be able to also generate clients for Ruby, Python and what else is out there.

[Gordon Hutchison]

I like this idea and was thinking of something similar when I made this post:

   https://groups.google.com/d/msg/microprofile/A8-J0Dk5LLQ/p50WcRGECgAJ

I think one of the value adds is that other services could be hooked in transparently
as part of the proxy/interceptor code based on what other annotations were present.
Gordon.

[Werner Keil]

Swagger Codegen https://swagger.io/swagger-codegen/ does this for most platforms or languages mentioned (OK not sure about the mainframe;-)

With Swagger contributor SmartBear involved, isn't that something they could help with?

[Emily Jiang]

I also think the Open API thread will have some overlap in this space. John, do you think OpenAPI is what you have in mind or you are talking about the ClientBuilder or WebTarget api? I know Arthur is very passionate about OpenAPI and he said he would continue when he is back from holiday. If it is in the similar area, one spec is better.

Emily

[Ken Finnigan]

A Type Safe API of external clients is something I've been working on for WF Swarm, building on top of JBoss RESTEasy to achieve it.

For me what we're discussing here is a different concern than OpenAPI, as the latter is only about defining the APIs within a service, at least to my understanding.

A Type Safe API also provides the ability to "bake into" the external interface definition things like service endpoint identifiers, circuit breaking info, etc.

Ken

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/49fc956e-f01b-4100-a451-b32fbe8f7e59%40googlegroups.com.

[John D. Ament]

Right, OpenAPI is a way to describe your API to consumers.  A type safe API is how an application developer can invoke HTTP calls without having to worry about the underlying structure and leverage POJOs etc for the client.  Depending on how feature rich OpenAPI support is, you may be able to point to a swagger.json and get a type safe client from that.

John

[Heiko Rupp]

Yes, this is what I meant. 

Or if the API has the Swagger annotations, then it is possible via annotation processor to extract the Swagger information plus the Java type information to have everything need to create those API clients.

[Arthur De Magalhaes]

Hey all,

Catching up on the discussion as I just got back from vacation. =) 

Yes, the Swagger codegen tools currently build a very nice POJO / model based JAXRS client from a given OpenAPI / Swagger document.  You can see an example by going to the online swagger editor (http://editor.swagger.io/#/) and picking "Generate Client -> Java".    The generated type-safe classes make it a lot easier to invoke the server endpoint.  

Since we're currently starting a proposal for OpenAPI server-side support based on the Swagger models/annotations, perhaps it's best to stay consistent and look at the Swagger client generation and how it can be shaped to fit into MP?  

Thanks,

Arthur

[John D. Ament]

That sounds like a plan.  Basically, I would expect to see a microprofile option on that screen that generated a client based on our specs (e.g. JAX-RS annotations, using JSON-B for POJOs, CDI injection, etc).  

Its sounding like this is positive so I'll get the bugzilla ticket open.

John

[John D. Ament]

Eclipse bugzilla is https://bugs.eclipse.org/bugs/show_bug.cgi?id=519275

Will likely require a PL to +1 it.

[Emily Jiang]

Just for clarification: so are we going to have two repo:

microprofile-rest-client [created by John]

microprofile-open-api [to be created by Arthur and/or Tony] 

or just one repo

microprofile-open-api [cover both client and server]

Ideas?

Emily

[Ken Finnigan]

For now I'm ok with them being separate, as implementations may only want to implement a client type safe API and not Open API.

With the caveat that in the future we may see overlap and want to merge them.

Ken

--
You received this message because you are subscribed to the Google Groups "MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile+unsubscribe@googlegroups.com.
To post to this group, send email to microp...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/63905caf-5a32-49d1-a9aa-e416a6b2730b%40googlegroups.com.

[John D. Ament]

Agreed.  We shouldn't fall into the premature optimization pit too early.

[Arthur De Magalhaes]

+1.   awesome =)

related question:  for the OpenAPI proposal that I am working on with Tony, should we work on the sandbox first (https://github.com/eclipse/microprofile-sandbox) or open a bugzilla ticket to create microprofile-open-api?  

Thx,

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.

To post to this group, send email to microp...@googlegroups.com.

[Emily Jiang]

Arthur,

I suggest you directly create a repo to start working as the general consensus for this spec is "go ahead" IIRC. You can follow an instruction here. The sandbox is used by someone who would like to prototype first before committing to do a spec.

Emily

[Heiko Rupp]

I was yesterday at Java Forum Stuttgart, where Johannes Fiala showed swagger codegen in action, and this enforces my belief that we should go that route.

My Understanding was also that codegen can depending on what parameters you give not only generate the classes for the respective API objects, but also the underlying http client code. So from my point of view no separate "hand-coded" client is needed.

[Arthur De Magalhaes]

Yup, you get the standard HTTP client code (allows for configuration, etc), plus the API models (POJOs, like Pet, User, etc), plus the API calls themselves (for example, a method "getPet" for "GET /pet".  

- Arthur

[John D. Ament]

I took a look at how the client is generated.  To me, it looks like this could be implemented as an annotation processor.  However, since this is consumer side I feel strongly that we shouldn't mandate OpenAPI requirements, instead have support for OpenAPI generated clients.  E.g. json -> JAX-RS interfaces -> impls.

I'd strongly suggest that you create a ticket (or tickets) at https://github.com/eclipse/microprofile-rest-client/issues to work through the ideas.

John