Understanding GraphQL as a RESTful API Developer
Although REST is still dominating the world of APIs there is an interesting trend towards GraphQL that is adopted by many developers and this is my take in understanding what practical changes are there in a GraphQL API compare to a REST and what this means to frontend and backend developers.
Let’s consider the following classic example which is quite common in these Covid times, an e-commerce store with their online webiste and mobile application. With a REST API based backend following views of a logged in user will be maintained as follows.
the top 10 recommended products (based on his/her previous purchases) : users/<id>/recommendations
Loyalty discounts for the season based on the points obtained by the user :users/<id>/discounts
With this approach,
- Multiple endpoints need to be invoked to access the necessary data for these 2 views.
- More frontend iterations are requried. For the recommendations view, frontend developers need to traverse through all the recommendations(received from the API call) to retrieve the top results; top 5 for the mobile app and top 10 for the portal.
- Frontend developers do not have the freedom to retrieve the exact (and only that) information they need in one go given the fixed data structure.
- It is impossible for backend developers to provide the exact information to their clients, as it is not possible to know the exact information required by each and every client.
Most of these concerns are due to over and unde fetching data since the client cannot query for the exact data that he/she needs.
GraphQL is a query language for APIs and [1] is a good resource to understand GraphQL in detail, but in simple terms GraphQL works based on a schema (SDL) that is defined which acts as the contract between the client and the server. A graphQL service is defined with a set of types (and fields for those types) and resolver functions for those fields.The clients can fetch the data with queries and perform mutations to create/update/delete data. Since the data structure is not fixed, the response sent depends on the structure of the query that is presented by the client.
A defined GraphQL schema can be retreived through introspection where the client can understand the different types and fields included in a given schema. Through this observation, the client can independently fetch the exact data that is required in the requested format.
Following is how the previous data views can be obtained through a GraphQL API.
With this approach,
- A single request can fetch multiple resources.
- The clients can query for the exact set of data that they require from the server. No more over or under fetching.
- There is no fixed data structure with the response hence clients can define various queries to obtain the data directly. Therefore client-side changes can be performed without any extra changes at the server-side.
This flexibility of GraphQL can be beneficial to increase the efficiency between development teams. A good governance in the schema definition can help the participating teams to work independently and define the domain to satisfy their needs. For example once the requirements and user-stories are layed out, backend , frontend and UI engineers can come together to define the graphQL schema and shape the schema to help each others viewpoints.
