Beyond REST with GraphQL

A dynamic back-end for a dynamic front-end

Photo by Ferenc Horvath on Unsplash

GraphQL in a nutshell

Enables each client to retrieve exactly the data it requires in a single round trip to the server.

A query language and a runtime which is better suitable for Single page applications and Mobile apps.

• GraphQL API has only one endpoint
• GraphQL API is self documented
• GraphQL request / response body is just JSON

Every platform that can do http request and process the JSON response can consume a GraphQL API.

GraphQL API structure

GraphQL makes use of Schema which is composed of

• Query
• Mutation
• Subscription

GraphQL Schema

Schema can be queried as follows , it will include all predefined and custom query types

{
 __schema {
  types {
   name
  }
 }
}

Think in graphs, not endpoints

Query:

GET data by specifying fields (to avoid over / under fetching) to be retrieved from the server. Arguments can also be passed in the query to filter the data

GET a product with a specific Id (variable: $productId)

Note: Spaces , Commas , New lines are all optional in GraphQL query

• To improve performance by avoiding multiple http round trips to the server, multiple queries can be included in one request.
  It is one of the main advantages of GraphQL over REST where you will have to make individual API request per resource.
• Aliases can be used to have independent client side changes. E-g on the server-side the field can be called “product” but on the client-side it can be renamed to “product1” by using alias

GET multiple products with aliases (product1, product2) in one request

Note: In GraphQL with multiple queries in one request; the slowest query determines the response time.
So If rendering of the view depends on the combined results of the queries, then its optimal to combine the queries in one request otherwise make a request on demand.

• Directives can be used to avoid over-fetching by retrieving some field(s) only on specific condition

Include directive “$includeSupplier” with default value “false”

• Repeated set of fields in different queries can be shared with Fragment

Fragment “productInfo”

Mutation:

Mutations are used to add/update the data.
Mutation == query with input object. Input is received by the schema as an argument.
On successful process the object is send back. However need to specify the fields to be retrieved in the response after successful operation.

Mutation to create a product

Note: Input object can also be defined as a variable

Subscription:

Subscription is a native feature of GraphQL that provides the real-time functionality.
The client initially opens up a long-lived connection to the server by sending a subscription query that specifies which event it is interested in. Every time this particular event happens, the server uses the connection to push the event data to the subscribed client(s).
Websockets are typically used to notify the client. In this setup, the server maintains a steady connection to its subscribed client(s)

Subscription for new product

Additional resources:

GraphQL schema language cheat sheet

How to GraphQL

GraphQL Hub

Using Postman with GraphQL API

GraphQL Vs OData