Separate project for MP GraphQL Client APIs?

[Andy McCright]

Hi All,

When we started the MP GraphQL project, we had intended to produce a Client API in a future release - an API similar to the JAX-RS Client API / MP Rest Client API for REST.  Now that MP GraphQL 1.0 is released, we are looking into the best way to create the Client API and wanted some guidance on the subject.

Something we are considering is whether the client should be in it's own project or not.  On the one hand we could follow Jakarta's pattern where the client APIs are part of the server APIs - in many cases this is fine, but then in other cases a user might get more than they really need - so maybe some separation is good.  So, then we could separate the client APIs into a separate maven project in the same GitHub project or we could create a completely separate GitHub project for the client (similar to how MP Rest Client is completely separate from JAX-RS).  

Thanks in advance for any thoughts or advice on this!

[John Clingan]

Separate spec. I recall having this conversation a decade ago in the Java EE context (JMS context, IIRC). An individual (or vendor) should be able to offer only a server (or a client) and claim itself compatible. It may be because  of resourcing limitation (perhaps a 1 or 2 person team)  or product/community focus ("we create developer tooling").

Alternatively, a spec could define this separation within the spec (EJB/EJB Lite, Java EE/Web Profile) so an implementor can claim compatibility server or client, or both.

However, there does need to be separation, IMHO, to proliferate the value of the MicroProfile brand and MicroProfile support in the broader market.

Good question!

[Andy McCright]

Thanks for the response John!

I kinda think we have a few options:

1) Don't separate at all - same repo and maven artifacts for client and server.

    Pros: Everything is in one place - implementers/users only have one Maven dependency to pull in.

    Cons: Implementors must implement both to be compliant.  Harder to separate for vendors who just want one or the other.

2) Separate maven artifacts, but same GitHub repo.

    Pros: Implementors and users can choose to use the client or server (or both) with much greater ease.  Single spec document for both.

    Cons: Users/implementors need multiple dependencies to use both server and client APIs.

3) Separate GitHub repos.

    Pros: Implementors and users can choose to use the client or server (or both) with much greater ease. Separate release schedule (e.g.. we could release MP GraphQL Server 2.0, while leaving MP GraphQL Client at 1.1).

    Cons: Users/implementors need multiple dependencies to use both server and client APIs. More setup/release/paperwork/etc. work.

I'm personally leaning toward re-using the same GitHub repo but creating separate Maven artifacts for server and client.  Aside from the benefits listed above, it also gives us more flexibility - we could always move it to a separate GitHub repo in the future if we needed to. 

I'd still like to hear more feedback because this decision may have impact on other future MP APIs (for example, maybe we do a gRPC API - and GraphQL might set the precedent for how those APIs might be split). 

Thanks again,

Andy

[Amelia Eiras]

Andy, 

Thanks for bringing this topic to Misc space during today's community call & the above write-up, you rock! 

Leaning towards option 2 for the reasons you stated today, listed below, plus that it seems that its maintenance will be easier to own and adjust with room for changing it without fear of halting innovation. 

Issues with option 1:

• lack of flexibility, added debt thrown the user. 

Issues with option 3:

• more debt added to MP INFRA- we still need to tackle "growing pains". This option to me seems to add debt to already a problem. 

[John Clingan]

Like Amelia, I like 2) as well. Here is why:

1) It separates the client from server in terms of compatibility. Implementations can choose one, the other, or both and still claim compatibility.

2) There will need to be a formalized difference. GraphQL and GraphQL Client. Implementations that support both should specify support for one, the other, or both

3) Keeping them in the same spec revs the versions together. It becomes absolutely clear that the two were tested together.

4) IMHO, this is not about independent evolution, this is about 1). As a result, this should also imply that both GraphQL and GraphQL client support the same feature at the same time. It would not look good if GraphQL 1.x supports a feature, and then GraphQL Client 1.y later adds support for that same feature. This is implied by being in the same spec document.

Worst case, we can completely split later to separate repos.

On Tuesday, March 17, 2020 at 11:43:44 AM UTC-7, Andy McCright wrote:

[Ken Finnigan]

I'm leaning towards option 2) as well.

However, how would the Client be included in the spec and would there be a separate TCK for the Client?

Put another way, for an implementation to claim it's "compatible" with MP GraphQL would it need to implement the server and client, or only the server and the client is optional?

--
You received this message because you are subscribed to the Google Groups "Eclipse MicroProfile" group.
To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/b5f08a12-a6ad-4fd4-9d44-0b72962679e5%40googlegroups.com.

[John Clingan]

There would have to be a separate discreet TCK, IMHO. This  would enable:

1) Run server TCK only

2) Run client TCK only

3) Run both TCKs and claim compatibility for both.

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

[Ken Finnigan]

I think this also heightens the need for the "growing pains" discussion, as how this work is done would likely be impacted

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

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/b5f08a12-a6ad-4fd4-9d44-0b72962679e5%40googlegroups.com.

--

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

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/00b3b8e1-b411-4b98-ab15-94f69d33b965%40googlegroups.com.

[Andy McCright]

My thought is that we would have a single spec document but have separate sections the clearly detail what is required for the client and what is required for the server.

As for the TCK, we would need a separate Maven artifact for the client TCK.  So our root folder directory would look something like:

client-api // publishes client API
client-tck // publishes client TCK
server-api // publishes existing server API artifact
server-tck // publishes existing server TCK artifact
spec       // publishes spec as PDF and HTML - separate sections for client vs server

A client-only implementor would only need to use the Client API artifact and would only need to pass the Client TCK.  Likewise for a server-only implementor.

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

[Phillip Krüger]

I agree with this structure Andy. I should be easy enough to also split the spec into 2 modules and combined them using maven.

How about a tree structure, rather than this flat structure :

server (parent for server)
- spec (server spec)
- api (server api as it is today)
- tck (server TCK as it is today)
client
- spec (client spec)
- api (client api)
- tck (client TCK)
spec (combined spec, pulling from above)

[Emily Jiang]

With all of these separate API, TCK for client and server, I think we are better off to create a dedicated repo for graphql-client.

With this dedicated repo, it is very clear that which runtime supports client, server, client+server. There will be no confusion. The client and server can evolve separately in their own pace. It is much easier to manage the lifecycle and sort out issues.

Therefore, I think option 3 is better.

I am speaking directly from some experience from MP Reactive Streams. Originally, it was one repo to hold operators and messaging. Even though two artifacts were produced, it was difficult and messy to manage. Therefore, two repos were created and they evolve separately, which is much clearer.

Thanks

Emily

[Werner Keil]

Hi,

I noticed a rather long and hard to follow thread between Bill, Andy and many other folks, but could you provide a quick and easy summary, e.g.: should the API and TCK artifacts be separate ideally even a separate repository?

Thanks,

Werner

[Ken Finnigan]

Werner

You're referring to a discussion on the Jakarta EE mailing list.

In MicroProfile the TCKs are always in the same repository, but they are separate artifacts.

Ken

--

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

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/fb9d7a8a-d526-4939-8fce-7ab3d7c9969d%40googlegroups.com.

[Werner Keil]

Is that (separate artifact) sufficient to make them compatible with Jakarta EE, say MicroProfile Config was intended to be the config solution for a future Jakarta EE version?

Werner

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

[Ken Finnigan]

I don't see how what you're describing has any bearing on a discussion around how to add a GraphQL Client capability into MP?

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/cd7fffd8-35e7-404a-99dd-c39917491232%40googlegroups.com.

[Rüdiger zu Dohna]

I have a tendency to option 2. But I have some questions:

Actually MP Rest Client strongly depends on JAX-RS, reusing the annotations. Depending on how you plan the GraphQL Client to work, there may be some limitations on how to separate them best. Will it use the same annotations? How will it work? Schema-first, i.e. generating typesafe query APIs in a separate build step or in an annotation processor? Or code-first like in MP Rest Client, i.e. you could reuse the API java classes of the server or write your own? Both have their pros and cons, and this decision may have an impact on how to best structure the artifacts.

Would MP GraphQL Client start off as a new sandbox project?

BTW as it hasn't been mentioned here before: we could also produce three artifacts: mp-graphql-server, mp-graphql-client, and mp-graphql which is empty but has dependencies of the former two.

[Phillip Kruger]

Hi Rüdiger

See this issue for some information of the planned low-level client:

https://github.com/eclipse/microprofile-graphql/issues/96

(Also note the pdf link in the last comment)

Cheers

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

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/488c852f-20f9-4d76-a620-e6e9fd47cfac%40googlegroups.com.

[Andy McCright]

Good questions Rüdiger.  For the low-level client, as Phillip mentioned, it will mainly just have a dependency on JSON-P - it won't use annotations from the server API.  The idea is similar to using the JAX-RS Client APIs.  

The high-level MP GraphQL Client API will be more like the MP Rest Client, and likely will use annotations that are shared with the server API.  This might require a bit of refactoring so that we have a "common"/"core" artifact with the annotations that would be shared between the server and high-level client, a "server" artifact with the server-only APIs, and a "client" artifact with the client-only APIs.

On Thursday, March 19, 2020 at 1:36:24 AM UTC-5, Phillip Krüger wrote:

Hi Rüdiger

See this issue for some information of the planned low-level client:

https://github.com/eclipse/microprofile-graphql/issues/96

(Also note the pdf link in the last comment)

Cheers

On Thu, Mar 19, 2020 at 6:47 AM Rüdiger zu Dohna <ruedige...@codecentric.de> wrote:

I have a tendency to option 2. But I have some questions:

Actually MP Rest Client strongly depends on JAX-RS, reusing the annotations. Depending on how you plan the GraphQL Client to work, there may be some limitations on how to separate them best. Will it use the same annotations? How will it work? Schema-first, i.e. generating typesafe query APIs in a separate build step or in an annotation processor? Or code-first like in MP Rest Client, i.e. you could reuse the API java classes of the server or write your own? Both have their pros and cons, and this decision may have an impact on how to best structure the artifacts.

Would MP GraphQL Client start off as a new sandbox project?

BTW as it hasn't been mentioned here before: we could also produce three artifacts: mp-graphql-server, mp-graphql-client, and mp-graphql which is empty but has dependencies of the former two.

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

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

[Emily Jiang]

I still think it is confusing to share one repo for two artifacts (option 2) while the two things advance differently. I am not sure how much it gains while using 2 separate repos is so much clear.

Emily

[Ken Finnigan]

Though the APIs would advance differently, wouldn't they always be "in sync" with respect to communicating with each other?

If that's the case, having them released on the same version makes sense to me

To unsubscribe from this group and stop receiving emails from it, send an email to microprofile...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/42c95d28-7ca3-42fb-8fd3-0392db352830%40googlegroups.com.

[Andy McCright]

The low-level client could evolve independent from the server APIs, but our vision for the high level client really should be tied to the server APIs.  It would most likely share annotations, like @Query/@Mutation/etc. (similar to how JAX-RS and MP Rest Client share things like @Path/@GET/etc.).

In our last project meeting we evaluated the feedback from this thread (many thanks for all of the feedback), and we decided to go with option #2.  If we think that it makes sense to separate it further into separate GitHub repositories, we can always do that at a later time.

Thanks again for the discussion!

To view this discussion on the web visit https://groups.google.com/d/msgid/microprofile/42c95d28-7ca3-42fb-8fd3-0392db352830%40googlegroups.com.