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.
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.
Let's look at drawbacks of REST
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.
So we talked about how schemas allow you to define contract between the front and the back, let's detail it more accurately.
- 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.
- 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
Let's get back to the subscription feature
- 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)
The question still pending is: how do you do it?
GraphQL supports a lot of languages, there is pratically any languages: check https://grapql.org/code/#graphql-clients
Let's look at the backend!
In java the main client is graphql-java, it is the core engine.
There is a version for microservices: MicroProfile GraphQl
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.
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.
Let's look at the frontend!
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
Okay, so we talk about GraphQL features, the question now is Why not using it?
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