GraphQL – The Best Thing Facebook Invented

What is GraphQL?

GraphQL is a framework and specification of how to retrieve data via APIs. It was developed by Facebook and publicly released in 2015 and the project has moved to a newly-established GraphQL Foundation, hosted by the non profit Linux Foundation.

This is important to allow for the framework to be come independent of FB and become open source without any conflicts of interest.

Here’s a Quick Primer:

Technical Breakdown

• GraphQL has both the server component and client components which are detailed below.
• Server component:
  • API end point which includes:
    • Type definitions – shape of data i.e. Schema
    • Resolvers – function that maps to the schema i.e. how to map the incoming query to the data objects that should returned
  • The server takes type definitions + resolvers and exposes them through an end point
  • Only one end point is needed
• Client component:
  • Allows the front end to be able to query from a GraphQL endpoint

Example Query:

{
	user (id: 3500401) {
		id,
		name,
		isViewerFriend,
		profilePicture(size: 50) {
			uri,
			width,
			height
		}
	}
}

Example Response

{
	"user" : {
		"id": 3500401,
		"name": "Dale Sun",
		"isViewerFriend": true,
		"profilePicture": {
			"uri": "http://youmust.construct/morepylons/jpg",
			"width": 50,
			"height": 50
		}
	}
}

The “So What”?

GraphQL solves for following challenges:

• Relational queries saves the number of rounds trips instead i.e.
  • Get Ids using API endpoint 1
  • Then use Ids that are returned for endpoint 2
• Over-fetching data
• Required detailed documentation for each endpoint

REST vs GraphQL

This is a great video that looks at Rest vs GraphQL

Here is a summary of key takeaways from the video in table format:

Benefits

REST Benefits	GraphQL Benefits
Indefinite scaling	Easy to start
High performance (esp. over HTTP2)	Time to market for servers and clients
Proven and works with any representation and media types	Amazing development experience
Decoupling of client and server = independent evolution	Easier to keep consistent and govern
Links across APIs

Costs

REST Costs	GraphQL Costs
Large entry barrier to training and learning	Neglects challenges of distributed systems (microservice architecture)
Huge paradigm shift from SOAP = challenge for enterprise level development	Server and Clients coupled, leading to greater risk and technical debt
Requires client side discipline to meet specs	Limited media type support
Limiting API description formats	Query optimisation
Challenge to maintain (governance and consistency)	Low but increasing adoption

Use cases

Use REST if	Use GraphQL if
Building a system that lasts	Talking to yourself (frontend-backend)
In need of content negotiation (language)	Instead of so-called-REST
Precise authentication, authorization rate limiting is needed	Short term project
Interlinking resource between APIs	Use-cases are
Using mixed media types	Just accessing data without the need for infrastructure/caching
Scaleability is a factor	Wanting to achieve Amazing Design Experience with little effort

Other Resources

• GraphQL Sandbox: GraphiQL – https://lucasconstantino.github.io/graphiql-online/
• API Mocking Tool: FakeQL – https://fakeql.com/

---