What is GraphQL?

It is an an alternate approach to client/server communication

=>Request asking to give an hero

=>Response coming back

That's the idea: You send query and you get data back.

The difference is that it does not use REST.

And the client can decide what it wants back (here only hero name property).

That helps with banwith issues and that eases the parsing on the client side.

It was created by Facebook in 2012.

It was open sourced in 2015.

And the GraphQL Foundation started in 2017.

It is used by many large companies: lyft, Twitter, Paypal, NBC.

So GraphQL is doing well in providing an alternate way for client/server interaction.

WhyGraphQL?

If you got a REST application that's working fine, why bother with GraphQL?

Here the benefits of GraphQL:

• Client decides what data it wants
• Server decides where to get it (from one database, or from one or more servers, services etc)
• Well suited for BFFs (provide one consolidated API from the frontend by aggregating data from several other services)

One of the main differences is that there is a single consolidated, dynamic endpoint which supports a particular GraphQL schema

which may supports x number of queries/types of queries.

Another feature is subscription, which is essentialy the ability to be notified of changes to data.

For example, I want to subscribe to heroes, and everytime there's a new hero added I want to get the information pushed to me.

So subscription is very powerful, by adding  push support on top of GraphQL features.

Drawbacks of REST

• Endpoint decides what data is returned (It's a very fixed contract)
• Data can be split amongst several calls
• No specific data format (fo example it can return a string rather than JSON)
• Layout of the data is up to the endpoint
• No push standard

Demo with the SW (Star Wars) API with Altair

• Basic query
• Query with parameter
• Error handling

That demo shows that there is a lot of flexibility and a standard way to return errors.

Schemas 

• Type-safe contract between client and server (You can't put arbitrary types that are not defined by the schema)
• Client can only request data defined in the schema (You can't add additional properties that are not defined)
• Versioning handled through deprecation (not by URL pathname variation like in REST --v1/whatever replaced by v2/whatever--, also it is interesting not managing versions, you have to purge the deprecated fields and confront the changes to the clients)

In the end a schema is just a document.

Design approaches

• Schema first development (where you build a document which you use as a contract between the front/back, and then you build the code in TS & Java with code generators)
• Code first (it is when the backend drives the schema; you can generate automatically the schema from the backend and consume it in the front that way)
• Make this decision up front 

Subscriptions

• Allows server to push changes to client (very useful when need real-time updates -- it is one of the greatest feature of GraphQL)
• Transport independent (web socket is most common)

How?

GraphQL supports a lot of languages, there is pratically any languages: check https://grapql.org/code/#graphql-clients

In java the main client is graphql-java, it is the core engine.

There is a version for microservices: MicroProfile GraphQl

There is also GraphQL Java Tools, lets you do GraphQL with schema first: https://www.graphql-java-kickstart.com/tools/schema-definition/ 👇

Then you have a resolver which responds to a query:

If you're using SpringBoot, GraphQL quicks start is the best way to get started: https://www.graphql-java-kickstart.com/spring-boot/

There are nice starters provided.

Here an example: https://github.com/phillip-kruger/graphql-example/blob/main/quarkus-example/src/main/java/com/github/phillipkruger/user/graphql/PersonGraphQLApi.java

This example shows that GraphQL is a mean to get data back and forth, it doesn't care about authentication, where you get the data as long as you provide it in the right interface.

GraphQL Kick start remains more powerful because it supports subscriptions.

On the front end it is also quite straightforward:

With Apollo, you define  the GraphQL query:

And in your component, you define the method fetching the data:

Note: there is an integration tool with Angular

Why not GraphQL ?

Take a look at the drawbacks:

• Type schemas=> defined data format:  Client needs to know what data it wants
• For basic endpoint/few data to return, there's no really great reason to use GraphQL
• Remember it is not REST, so if your staff does know above all REST and you're lacking time, it may be not a good option
• There is a lot features to dig in to go to the next level of GraphQL use

Don't forget REST has benefits:

• Simpler, easier to get started
• Better suited for read-only or low data APIs
• It's REST
• No specific data format