Designing GraphQL API’s Schema

Welcome back to the third post on how to design and implement GraphQL API’s for use in large scale projects , involving many developers and also how to design it so that it is modular and scalable.

In the last blog post titled Dissecting GraphQL Queries we discussed what comprises of a GraphQL query and how do we subscribe to, fetch and publish data, so in this blog we will be discussing more on how to design the schemas.

Lets start with the GraphQL Schema

As you know when we design the complexity of data fetching using schemas increases with the increase in complexity of the UI, for example lets take the example of a blog and an e-commerce website:

This blog happens to have a simple UI where there are limited components to fetch the data for making the schema designing process a simpler task.

However if you look at something like amazon.in , the schema design suddenly becomes more complex with the data being more complex in nature to fetch.

Most of the benefits offered by GraphQL are due to GraphQL Schemas. Schemas enable automatic code generation, validation and parsing, introspection, and type safety for your APIs.

Writing the GraphQL schema

The GraphQL spec defines a language called the Schema Definition Language (SDL) to write GraphQL schemas.

You use the available types defined by SDL to compose your GraphQL schema. We cover four of the types in this article:

• Object type
• Scalar type
• Query type
• Mutation type

You’ll learn more about these types (and others) in upcoming articles.

It can be challenging to represent types as GraphQL schema, especially with complex and extensive UIs. However, follow the four steps below to represent your types as a GraphQL schema like a pro.

A well designed schema will not only catch runtime errors but also catch build errors.

The schema in effect is a description of the data the client can request from the server , moreover it implements functions like queries and mutations which in turn fetch and publish data to/from data sources.

Lets talk about the aforementioned blog post, so every blog post has a blog title , body and image component, also every blog is written by a user on different dates , so in effect we can design a schema which has a user component and a blog component.

So what we do basically is that we make a user schema with the username , and an array of blogs of the user, with each blog having title , body, image and date.

Here we design the schema in such a way that the user data contract already contains the blog data contract and then we can write a query which will in effect fetch the blog as well as user metadata in one call.

The goal here is to minimize as many api calls as possible , keeping in mind the hierarchy of the UI and how the data are related to each other in terms of functionality of populating the UI.

We write a query to fetch the user component data and then the blogs component data and then the schema puts them together in one call.

When the LoadHomePage query is requested by the front end it is going to fetch the data from both the queries and put them in the response as defined in the schema for user which includes the blog return inside.

GraphQL schema defines the signature of your GraphQL API, but it’s not yet functional.

To make it functional, you still need to run a GraphQL web server, write server-side code, and use a database to store and retrieve the data.

Conclusion

In this blog post, you learned an intuitive approach to design your GraphQL schema and some of the GraphQL types defined by the Schema Definition Language (SDL).

Keep looking at this space for more on GraphQL and how it fares in the micro service oriented architecture environment.