guidance on whether to use Annotation based spring boot graphql server

Question

I am developing a new project with spring boot and graphql. I am confused on how to proceed because there are 2 ways to develop it, one is via the graphqls file and Annotation based approach. I prefer Annotation based approach but are they stable. exmaple : https://github.com/leangen/graphql-spqr.

Answer 1

I don't think there is a good or a bad answer to the "how to proceed" question. There are two different approaches to build your graphql server (with graphl-java, graphql-java-tools, graphql-spqr), and each method has its advantages and inconvenients. All those library propose a springboot starter. Note that I never used graphql-spqr.

Schema first (with graphql-java or graphql-java-tools)

In this approach you first create a SDL file. The graphql library will parse it, and "all" you have to do is wire each graphql type to its data fetcher. The graphql-java-tools can even do the wiring for you.

Advantage

• no need to enter into the detail of how the Graphql schema is built server side
• you have a nice graphqls schema file that can be read and used by a client, easying the charge of building a graphql client
• you actually define your api first (SDL schema): changing the implementation of the api will not require any change client side

Inconvenient

• no compile-time check. If something is not wired properly, an exception will be thrown at runtime. But this can be negated by using graphql-java-codegen that will generate for you the java classes and interfaces for your graphql types, unions, queries, enums, etc.
• if using graphql-java (no auto wiring), I felt I had to write long boring data fetchers. So I switched to graphql-java-tools.

Code first (with graphql-java or grapqhl-java-tools or graphql-spqr)

The graphql schema is built programmatically (through annotation with graphql-spqr or by building a GraphQLSchema object in graphql-java)

Advantage

• compile-time check
• no need to maintain both the SDL and the Domain class

Inconvenient

• as your schema is generated from your code base, changing your code base will change the api, which might not be great for the clients depending on it.

This is my opinion on those different framework and I would be happy to be shown that I am in the wrong. The ultimate decision depends on your project: the size, if there is an existing code base, etc.

Answer 2

I second AllirionX's answer and just want to add a few details.

Firstly, to answer your question: yes, SPQR has been pretty stable for quite a while now. Many teams are successfully using it in production. The only reason it is still in 0.X versions is the lack of documentation, but an occasional small breaking change in the API does occur.

Secondly, I'd also like to add that going code-first doesn't mean you can't also go contract-first. In fact, I'd argue you should still develop in that style. The only difference is that you get to write your contracts as Java interfaces instead of a new language.

As I highlight in SPQR's README:

Note that developing in the code-first style is still effectively schema-first, the difference is that you develop your schema not in yet another language, but in Java, with your IDE, the compiler and all your tools helping you. Breaking changes to the schema mean the compilation will fail. No need for linters or other fragile hacks.

So whether the API (as described by the interfaces) changes as the other code changes is entirely up to you. And if you need the SDL for any reason, it can always be generated from the executable schema or the introspection result.