Dive into GraphQL
Material used by myself to do an introductory workshop on GraphQL
How many times do you find API’s that re not well documented?
How many time you don’t agree with your workmates about the HTTP status?
How many times do you disagree with the chosen endpoint for a REST Service?
GraphQL is not a programming language, nor a a framework. GraphQL is just a specification that tells how we must implement our API’s
GraphQL is focused on API’s consumers, being the clients the ones who decide with data want bring from the server side.
GraphQL was invented by an engineering team at Facebook by 2012.
GraphQL was announced in 2015 and It’s currently maintained by the open source community.
Having a look at Facebook we find that a lot of information is showed in any page.
User details, family details, list of friends, working experience… Thinking of REST, this would imply several services requests….
Since GraphQL was published several companies have been adopting this specification in order to implement their own services.
Some of the most known companies are the ones in the picture.
Awesome this article written by Mark Stuart (Lead at Paypal)
A good way to understand GraphQL can be comparing it to REST.
REST provides an endpoint per each implemented service. Since Rest is implemented over HTTP protocol we need decide not only the endpoint but also the verb for our service.
GraphQL provides a single endpoint (usually /graphql) and all the services can be consumed pointing to this endpoint.
GraphQL is typed. This means that both, client & server known which information is sent. Even most importante the fact that we also know the type of the data.
GraphQL establishes a contract between client & server that makes communications easy.
Do you agree with your workmates when the API needs to be upgraded to a new version?
Versioned API is a .common practice in REST but GraphQL doesn’t bet for it. GraphQL proposes that API mustn’t be versioned. However, it provides mechanisms to deprecate old or unused data from our API’s
GraphQL is highly focused on making the life easier to the clients. The clients can always decided which data want to retrieve from the server.
However, in REST architectures this decision is taken by the server.
Again, as REST is coupled to HTTP protocol, it makes use of HTTP statuses in order to represent an error:
All GrahpQL responses will be a 200OK even when something failed. Error is defined inside the response body
Cache is implemented in HTTP protocol, so REST take advantage of this.
GraphQL cache doesn’t implement a cache mechanism so must be the client the one that decided how their data are cached. (In future posts I will explain how we can do it)
An amazing list of good practices to make safer our GraphQL service can be found here
Let’s do it
First of all, we need to write the contract for our service. This will permit both client and server establish the services endpoints.
If you have experience with OOP you see what an easy to understand is.
The best way to understand GraphQL is implementing a GraphQL service.
The application
We will implement a GraphQL API that will helps us to organize meetings in a company. The requirements for this application are:
- The API must provide a way to add rooms, employees and meetings
- Meetings can only be organized by employees but invited people can be both employees and external workers.
Write the domain models in the contract (the GraphQL schema)
Adding descriptions and comments to our API
Below, we see how API’s are described in GraphQL. This is really important when a client needs to understand our API’s.
Write operations provided by our API (query and mutations. Subscriptor will be explained in a future post)
Code implementation
Since this workshop is not focused on how implement a GraphQL you don’t need to spend time on it. On the hand, please checkout this project that implements the operations in the above GraphQL schema
To run the project, take one of the options
- make run: Docker is required
- make local: In this case you need to get a mongodb running locally on port 27017.
Once our GraphQL application is up and running we can consume the services.
- Open your browser and go to http://localhost:7000/graphql
Now you can save data into the database by making use of mutations
or read data with queries
As it was mentioned on the above, this is a material used by myself for doing a “Workshop of GraphQL”. Even the article go through several points, they are not taken in dept. Deeper articles are coming soon!
