GraphQL is a query language for your APIs. It helps us write simple, intuitive, precise queries to fetch data. It eases out the way we communicate with APIs.
Let’s take an example API, say we have a products API. In REST world you would have the API defined like
to get all products details
GET: http://path.to.site/api/products
or
to get single product details
GET: http://path.to.site/api/products/{id}
Now, let’s say Products has schema as
Product
- id: ID
- name: String
- description: String
- type: String
- category: String
- color: String
- height: Int
- width: Int
- weight: Float
Now by default, the REST API will return all the parameters associated with the entity. But say a client is only interested in the name and description of a product. GraphQL helps us write a simple query here.
query { product(id:5){ name description } }
This will return a response like
{ "data": { "product": { "name": "Red Shirt" "description": "Best cotton shirt available" } } }
This looks simple, so let’s make it a bit complicated. Say a product is associated with another entity called reviews. This entity manages product reviews by customers.
Reviews
- id: Id
- title: String
- details: String
- username: String
- isVerified: Boolean
- likesCount: Int
- commentsCount: Int
- comments: CommentAssociation
Now you can imagine in case of REST API, client needs to call additional API say
http://path.to.site/api/products/{id}/reviews/
With graphQL, we can achieve this with a single query
query { product(id:5){ name description reviews{ title description } } }
This will return a response like
{ "data": { "product": { "name": "Red Shirt", "description": "Best cotton shirt available", "reviews": [ { "title": "Good Shirt", "description": "Liked the shirt's color" }, { "title": "Awesome Shirt", "description": "Got it on sale" }, { "title": "Waste of Money", "description": "Clothing is not good" } ] } } }
We can see GraphQL solves multiple problems which were there with REST APIs. Two major problems we have evaluated in the examples above
Overfetching: We can explicitly mention all data we need from an API. So even if a Product model has 50 fields, we can specify which 4 fields we need as part of the response.
Multiple calls: Instead of making separate calls to Products and Product reviews, we could make a single query call. So instead of calling 5 different APIs and then clubbing the data on the client side, we can use GraphQL to merge the data into a single query.
Why Graph?
As we can see in the above examples, GraphQL helps us look at data in form of a connected graph. Instead of treating each entity as independent, we recognize the fact that these entities are related, for example, product and product reviews.
2 thoughts on “GraphQL- Getting started”