The Hitchhiker’s Guide To GraphQL

TLDR, pls visit the summary at the end.

Wait, What is GraphQL?

Is it a new query language? A new type of database? Some other JavaScript black magic? Nope, none of the above.

In a nutshell, GraphQL is a Query Language for APIs that describes how to ask for data and is generally used to load data from a server to a client. Firstly, it doesn’t have anything to do with databases. It is not an alternative to SQL. It is basically used to send/receive data between client and server using a minimum number of HTTP requests. In order to achieve this, you have to create relations between the entities programmatically(Graph Structure). That’s how it is called as a query language.

“Ask for what you need, get exactly that.”

Why GraphQL is a Better than REST API?

When you need to build an API, your mind will likely jump to REST, the standard for API creation. However, this is changing with the increase in GraphQL popularity. Let's see why GraphQL became popular within no time and why it is better than REST.

A Typical GraphQL API Architecture :

Benefits of GraphQL:

Resources Handling: - When you are building an application that consists of creating, reading, updating and deleting operations, in REST API, you would end up writing different routes thus creating a number of resource endpoints. In the GraphQL world, you write a query to ask for what you want(create, read, update, delete), and you get back exactly what you asked for with a single endpoint. GraphQL can handle all your application operations with a single endpoint.

REST vs GraphQL Architecture :

2. Data Fetching:

• Under-fetching - Under-fetching generally means that a specific endpoint doesn’t provide enough of the required information. The client will have to make additional requests to fetch everything it needs. A GraphQL query can solve an under-fetching issue in REST API with a single query wherein you get whatever you want. nothing more or nothing less. nevertheless, you can also filter how many records you want which is yet complex to achieve with REST API.
• Over fetching - Another problem we face with the REST API is over-fetching. — fetching excessive data that we don’t need. This REST implementation represents a huge waste bandwidth per request. With GraphQL, we can fetch the fields that we need and a list of records we’ve asked for with a simple query. 

Fun fact - Facebook faced these problems earlier and introduced GraphQL to avoid the issues mentioned above.

3. API Versioning:

With REST, it’s common to offer multiple API versions. However, GraphQL eliminates the need for versioning by deprecating APIs on a field level. GraphQL enables that by creating a uniform API across the entire application that isn’t limited by a specific storage engine. By using a single, evolving version, GraphQL APIs give apps continuous access to new features and encourage cleaner, more maintainable server code.

4. Debugging:

In REST, we simply check the HTTP headers for the status of the response, based on which we can determine what went wrong and how to handle it. Contrarily, if there is an error while processing GraphQL queries, the backend will provide a detailed error message including all the resolvers and referring to the exact query part at fault.

5. API Documentation:

With REST we can use Swagger, RAML or other technologies to document our API and explain the individual endpoints, what function they perform, and the parameters a developer can pass to them. GraphQL comes with self-documenting capability. i.e. auto generation of API documentation based on GraphQL schema as well as keeping it continuously in sync with any change to the API’s. 

6. A Powerful Playground (Positive developer experience as compared to REST)

GraphQL comes with a powerful Playground for better development workflows that make real-time requests to the schema, its features include interactive docs, an editor for GraphQL queries, tracing, sharing playgrounds, mutations, and subscriptions, validation, etc. Using the in-built GraphQL browser, you can experiment with the API and the data it exposes and also has a smart auto-complete feature.

GraphQL IDE :

Summary:

1. GraphQL is a Query Language for APIs that describes how to ask for data and is used to load data from a server to a client. Graph-based APIs model the data in terms of nodes and edges (objects and relationships) and allow the client to interact with multiple nodes in a single request.
2. GraphQL uses a single(or minimum number of) endpoints to send/receive data between client and server. it can handle all your application operations with a single endpoint.
3. Using GraphQL we can solve over-fetching and under-fetching issues. because, with the GraphQL, the client gets only the data that it asked for and with a minimum number of requests.
4. By using a single, evolving version, GraphQL APIs give apps continuous access to new features and encourage cleaner, more maintainable server code. 
5. Unlike REST showing HTTP error codes for an error, GraphQL will provide a detailed error message including all the resolvers and referring to the exact query/mutation part at fault.
6. GraphQL comes with self-documenting capability. i.e. auto generation of API documentation based on GraphQL schema. GraphQL keeps documentation in sync with API changes. So no need to re-document everything for API changes. Using the in-built GraphQL browser, you can experiment with the API and the data it exposes.
7. The GraphQL schema is at the center of every GraphQL server. It defines the server’s API, allowing clients to know which operations can be performed by the server and what fields and types that every query returns.
8. A GraphQL operation can either be a read or a write operation. GraphQL query is used to read or fetch the data while a mutation is used to write or alter the data. subscriptions are a GraphQL feature that allows a server to send data to its clients when a specific event happens.
9. A resolver is a function that is responsible for fetching data from the backend(Read Operations) and sending data to the backend(CUD Operations).

We discussed here, what is GraphQL, Benefits of GraphQL over REST and I hope this article somehow helped you to get started with GraphQL. This is a three-part series of articles. In the next article, let’s dive deep into the components we discussed earlier and build a simple CRUD application using GraphQL, Mongo and Node. Are you guys interested? Follow us!!.

Full version of this article(with more technical code walkthrough and components description) can be found here

Where to go from here?

1. https://www.howtographql.com
2. https://graphql.org/
3. https://www.apollographql.com/docs/tutorial/introduction/

Work with us!

We at DevopsInternational (an emerging technologies company focussed on Machine learning and Blockchain) are delivering value to customers and society with software craftsmanship. We have been helping social and environmental startups validate their idea through its product development and technology expertise. You can find more about our services on our website.