GraphQL, what, why, and when?

What is GraphQL?

GrpahQL is an open-source query language used to build APIs and provides powerful abilities over the traditional Rest API.

The client gets exactly what asked for:

GraphQL will always know what the client asked for, so the server will send exactly the requested data.

So if you think about it, this is really a huge advantage.

The client doesn't need to manipulate and normalize the retrieved data, we know exactly what to expect from our server.

As we know, this is possible with Rest API as well, but the server needs to maintain multiple endpoints for multiple data shapes that the client asks for where GraphQL will handle this case by a defined schema.

Single requests many resources:

Another powerful ability is getting to execute multiple operations using a single request.

What does that mean? We can combine multiple queries by a single request and get all the data we need.

It will save us a lot of time on the client-side. While getting the data from multiple requests will require more pending time.

The type system:

GraphQL is a strongly typed language. This system will provide to the server-side and the client-side a contract between them. It will determine if the query is valid or not and will describe clear errors.

Graphql playground:

Graphql provides out of a box a playground, graphical interface in a browser.

The playground is will give us an experience as an IDE and provide all the necessary information we need for the purpose of communicating to the server-side.

It is really helpful to explore the API and all its capabilities before we use it.

Why we should use GraphQL?

As we mentioned in the preview sections, GraphQL gives us a lot of benefits.

• Data exactly as requested (payload size).
• Single request multiple resources (reduce the number of requests from the client).
• Build-in documentation (playground, and typed system).
• Client experience, and developer productivity.

When we should use GraphQL?

Not all the scenarios are a good fit for GraphQL, so here are bullets when to use GraphQL, and when you shouldn't:

When you shouldn't:

• When you develop a simple application that doesn't require a lot of fields and a complex architecture, you should stick with a traditional Rest API. Because of over-complicate your implementation, it is like programming a super-computer to play tic-tac-toe.

• Because of the flexibility of the client’s requests, it can be a performance issue, why is that? The client can ask a deeply nested query or a lot of resources it can impact the server performance and even get him down, so the API should be carefully designed (define max depth, use Dataloader, and so on). So if you worry about performance issues, and you have a better solution with Rest API, you should stick to it.

• Most of the developers are familiar with Rest API more than GraphQL, in that case, it will be an overhead to use the GraphQL API instead of traditional Rest API, so it is be a problem when the developer doesn’t know how to get the most of the GraphQL’s benefits.

When you should:

• If the bandwidth is a matter to you, then you should consider using GraphQL. Because of the combined resources in a single request, it saves the bandwidth and reduces the waterfall requests.

• If you’re developing a complex system with many various objects with many fields and things like that you should consider using GraphQL, it will save you a lot of development time and experience.

• Any new feature or change in the data can be considered a breaking change in Rest API and that requires a new version. In another hand, GraphQL returns only the fields that are asked for, so we can add new features and type without creating breaking changes.

Conclusion:

GraphQL is a great tool with many advanced features that overcome the traditional Rest API in many scenarios. In each scenario, you should choose the right tool for the right goal.

We covered a few things that make GraphQL a powerful tool, and you should take into account when to use a Rest API and when to use GraphQL.