GraphQL Client - New typesafe API desired (and already prototyped)

[patriot1burke]

Summary: I started a rewrite of Smallrye GrapheQL typesafe client. Are you interested? I have a starting prototype.

I need to interact with Github's GraphQL API. Because of a limitation, Smallrye Graph QL Typesafe client is unusable. Specifically, raw strings field variables are "String!" while Smallrye treats strings as "String". I couldn't find a workaround for this from the docs. (Maybe there is something?).

I also found the client typesafeAPI awkward, more verbose than needed, and inefficient, so I wrote a replacement.

• nested apis.
  Github Graqph ql has a ton of nested queries under repository, where repository requires owner and name parameters. With Smallrye I had to provide these parameters for every different item under repository I was querying for. Parameter lists just got longer and longer. So, I wanted to create something like JAX-RS subresource locators, but on the client side. Here's an example:

interface GithubAPI {
     Repository repository(String owner, String name);
}

interface Repository {
      @Query
      DiscussionConnection discussions(int first);
... more methods ...
}

void main() {
    GithubAPI api = client.typesafeInterface(GithubAPI.class);
    Repository quarkusRepo = api.repository("quarkusio", "quarkus");


    DiscusssionConnection discussions = quarkusRepo.discussions(10);
    CommentConnection comments = quarkusRepo.comments(discussionId, 10);
}

So, basically given the above, I only have to enter in the repo field variables once, then can make any other queries I want on the Repository interface. The proxy automatically inserts query { repository(owner: "quarkusio", name: "quarkus" when calling @query methods under Repository interface.

• Query and variable namespaces

Next thing I found is that for Smallrye I had to model the whole graph schema in Java classes even though I wanted a small nested part of the graph. I wanted to create a shortcut for this. Here's an example

interface GithubAPI {
     Repository repository(String owner, String name);
}

interface Repository {
      @Query
      @Namespace("discussion")
      DiscussionCommentsConnection comments(@Namespace("repository.discussion") int number, int first, String after);


... more methods ...
}

The client proxy knows to navigate through the returned result json to the actual json node I want to unmarshal into DiscussionCommentsConnection.

The comments method would produce this query

query($owner: String!, $name: String!, $number: Int!, $first: Int!, $after: String!) {
    repository(owner: $owner, name: $name) {
         discussion(number: $number) {
              comments(first: $first, after: $after) {
                     ...
               }
          }
     }
}

• Various mapping annotations

@inputType on a method parameter specifies the variable type. Can also be put on a class too.
@GraphField on a method uses that value instead of the method name for a field reference
@variable on a method parameter specifies the field variable name instead of the default argument name.
@DefaultVariable on a method allows you to define default field variables and their values.

[cescoffier]

\CC @jmartisk

[jmartisk]

Because of a limitation, Smallrye Graph QL Typesafe client is unusable. Specifically, raw strings field variables are "String!" while Smallrye treats strings as "String"

You should be able to annotate the field with either jakarta.validation.constraints.NotNull or org.eclipse.microprofile.graphql.NonNull for that

nested apis

So what exactly does it fetch on the first call (when you call api.repository("quarkusio", "quarkus"))? Which fields will be retrieved? To me, this looks like lazy fetching with JPA, and I'm a bit worried about it breaking some core principles of GraphQL, which is being able to retrieve everything at once in one request. This is exactly why GraphQL was created as an alternative to REST and you're going in the opposite direction. If you have to split it into multiple calls to retrieve discussions, that means more network requests, and possible inconsistencies because there are no transactions (not in a portable way).

Another thing is that the Repository.discussions is not technically a query (but you apply the @Query annotation on it) - it's a subfield of a query result, but that's a minor problem

@t1 as the main author of the original typesafe client should be involved

[patriot1burke]

FYI: I do not use Smallrye or any of its annotations. I created my own typesafe client.

In my implementation. An un-annotated method that returns an interface returns a proxy that partially prebuilds the query string, but does not make an invocation. Only @query (or @mutation, etc.) annotated methods actually make an invocation to the server.

The query string is built from both the java method calls, parameters, and the return class/record of the @query method. The (nested) method calls built up the top layers of the schema/query, the method return class defines the remaining schema/query

nested apis

So what exactly does it fetch on the first call (when you call api.repository("quarkusio", "quarkus"))? Which fields will be retrieved?

Nothing is retrieved when you call api.repository("quarkusio", "quarkus"). This method builds up the initial query string posted to Github. When you call an actual @query method the rest of the query string is built.

To me, this looks like lazy fetching with JPA, and I'm a bit worried about it breaking some core principles of GraphQL,

There is no lazy fetching. The example pulls exactly what the app dev asks for. The benefit for the change is that the app dev doesn't have to provide or navigate enclosing parent classes for the result. I don't care about the repository object. I care about discusssions within a specific repository.

Another thing is that the Repository.discussions is not technically a query (but you apply the @Query annotation on it) - it's a subfield of a query result, but that's a minor problem

Again, I ditched Smallrye and wrote my own annotation API. Does that answer the question?

Repository.discussions() produces this query

query($owner: String!, $name: String!, $first: Int!) {
    repository(owner: $owner, name: $name) {
        discussions(first: $first) {
              nodes {
                    author { name }
                    body
                    ...
              }
        }
   }
}

Here's a better example:

public interface GithubAPI {

    Repository repository(String owner, String name);

    public interface Repository {
        @Query
        @DefaultVariables({
                @DefaultVariable(name = "orderBy", value = "{field: UPDATED_AT, direction: DESC}"),
                @DefaultVariable(namespace = ".nodes.comments", name = "first", value = "20")
        })
        DiscussionConnection discussions(int first, String after);

        Discussion discussion(int number);
    }

    public interface Discussion {
        @Query
        DiscussionCommentConnection comments(int first, String after);
    }
}

I'm iterating discussions and their comments to do some processing on them.

1. So I don't have to put repository owner and name in every query I make, I get a Repository instance that will set up some preprocessing for further requests

GithubAPI api = graphQLClient.target(GithubAPI.class);
Repository repo = api.repository("quarkusio", "quarkus");

2. I start pulling batches of discussions to process

DiscussionConnection discussions = null;
String after = null;
do {
   discussions = repo.discussions(50, after);
   after = discussions.pageInfo.endCursor;

   for (Discussion discussion : discussions.nodes) {
       processDiscussion(repo, discussion);
   }

} while (discussions.pageInfo.hasNextPage);

3. While I do pull comments with the batch discussions query, there may be more comments than I initially asked for. So, I need to get the comments of an individual discussion

void processDiscussion(Repository repo, Discusssion discussion) {
   if (discussion.comments.pageInfo.hasNextPage) {
       CommentsConnection moreComments = repo.discussion(discussion.number).comments(100, discussion.comments.pageInfo.endCursor);
   }
}

What's great about the above comments() method is that the graphql api knows how to construct the entire nested query:

query($owner: String!, $name: String!, $number: Int!, $first: Int!, $after: String!) {
    repository(owner: $owner, name: $name) {
         discussion(number: $number) {
              comments(first: $first, after: $after) {
                     ...
               }
          }
     }
}

[jmartisk]

Hmm, ok, I guess it would be useful, but it's hard to get a good picture for me from just this description. I guess this could warrant a discussion at the upcoming F2F if you want?

[patriot1burke]

Here's a working example:

https://github.com/patriot1burke/github-product-manager/blob/main/github-ingester/src/main/java/io/quarkiverse/github/api/GithubAPI.java

[jmartisk]

Thanks, I'll try to give it a go soon (somewhat busy now...). In any case, what is your goal, would you like to contribute this to smallrye as a second approach?

[patriot1burke]

Would contribute if at least one other person thinks its useful. Still need to create a quarkus extension though. Also dependent on Jackson if that makes a difference. I don't understand why JSON-B is so prevalent in Quarkus.

Talk to you about it in Prague?

[jmartisk]

For sure!