We previously discussed the difference between REST and SOAP for building APIs and web services. But there is an alternative solution that is becoming increasingly popular.

Better than all the REST?

GraphQL is a query language – or an interface description language – used to define how two applications talk to each other. It’s become so popular that GitHub is moving their API from REST to GraphQL.

GraphQL was built by Facebook as an improvement on a REST API. Retrieving a lot of complex data with REST requires multiple requests, and Facebook found the multiple roundtrips between client and server to be sub-optimal for their mobile applications. As such, they developed GraphQL as a language to optimise the number of requests, the size of the request payload, and the size of the response payload. Often you can fetch the data you’re interested in with one single call.

At a basic level, GraphQL lets you define data types, and actions that can be performed on those data types. These data types can be designed as nodes in an interface (e.g. User, Post, Photo), and you can model your data as a graph with paths between the nodes.

Each node is like an object with attributes. A User can have an ID, firstName, and lastName, a Post or a photo can have likes and comments. There can also be relationships defined between the nodes and their attributes. User1 is friends with User2 and User3, but User2 and User3 are not friends.

This graphical representation allows for intuitive and efficient requests for information from the database. Facebook use a specialised graphical database, but GraphQL can still work with traditional relational databases like MySQL, with the help of abstraction tools.

Queries and Mutations

Within a GraphQL setup, an application can request data with ‘Queries’, and create data with ‘Mutations’. These are the equivalents of ‘GET’ and ‘PUT’ requests in REST, but it has the advantage of increasing the amount of information retrieved per request.

A GraphQL query retrieves all of the requested information from the first node, then moves onto the next node to get the information, and then the next one, and so on until all of the information has been retrieved.

One of the other advantages of GraphQL is that the response to the queries mirror their response. For example the server query:

{
user(id: 1234) {
id
name
isViewerFriend
}
}

Would return this JSON response to the client:

{
“data”: {
“user”: {
“id”: “1234”,
“name”: “Stan Smith”,
“isViewerFriend”: true,
},
}
}

This basic query returns an obviously parallel response that shows that Stan Smith is a friend of the User. This definitive data shape makes GraphQL easy to learn and use, its hierarchical structure means that fewer requests are required, and there is no over-fetching because it only returns what was explicitly asked for. Mutations work in a similar fashion. If you want to create a new user, then you create a new node of type ‘user’.

GraphQL is a strongly-typed language, which means it checks that a query is syntactically correct and valid before execution. This makes sure that the query can only refer to types and fields that have been previously defined. To prevent error, it’s also possible to implement variables into the request that can be selected with drop-down menus, search fields, or filters.

When building web applications, you’ll need a powerful, scalable solution to host it. Visit the Fasthosts website for more information.