Is GraphQL the future of APIs?

For some time now, the paradigm for web service architecture has been RESTful services, which enable representations of resources from one system (usually in JSON form) to be made available to another over a network. 

A basic REST service might expose a /customer/ resource that returns a collection of all customers in a company’s system. An HTTP GET request to /customer/12/ would return the record for customer number 12, attributes as JSON properties. It’s this simplicity that has made REST so attractive. 

• Interested in APIs? Take a look at our guides to the best JavaScript APIs, HTML APIs and Google APIs

However, there are limitations to RESTful services that can make more complex use cases needlessly convoluted. As a result, in 2015, Facebook’s GraphQL was unleashed. GraphQL offers an alternative paradigm and language that overcomes many of the perceived shortcomings of REST, and alongside Facebook counts Twitter, GitHub and Pinterest among its users.

REST services provide responses in a format determined by the server, and aim to isolate resources based on a logical model. This introduces two issues that GraphQL sets out to solve: 

• Since the response structure is determined by the server, a typical REST response will provide more information than is necessary for the client. Changes to this response structure may be breaking and require versioning the API. Where development responsibilities are separated, this also places a dependency on the team developing the API to respond to changing front-end requirements. 
• It’s rare that meaningful functionality can be implemented by manipulating individual REST resources in isolation, resulting in ‘chatty’ APIs that require significant back and forth across the network to fulfil any practical 

Let’s say our RESTful /customer/ resources include a customer’s name, email, and a list of order IDs. We also have a separate collection of /order/ resources representing individual orders that include the product name. To get the names of all products a specific customer has ordered, we first need to retrieve the customer resource (GET /customer/12/), then get the order resource for each item in the array of order IDs (GET /order/#/). Along the way, we also receive the customer email, which we don’t need.

Conversely, GraphQL lets the client specify the exact information needed as a single request. The complexity of gathering this information and consolidating it into the required format is shifted to the server. A server-side runtime sits in front of your application, and processes these requests based on a set of data types and functions you define.

To fulfil our need to obtain a list of products a customer has ordered, the GraphQL client will tell the server that it wants the customer name, and a collection containing the product names of their orders. The server will return only this information. In GraphQL terms, this is a “query”. If we want to modify resources on the server, we use a “mutation” (as a POST request). These are defined similarly to queries but each request specifies a function that is implemented on the server to update data. 

Many developers are excited about GraphQL, and it’s likely that its footprint will continue to grow. A turning point will come when it reaches sufficient maturity that corporations become comfortable using it. The best place to start learning how to create and deploy GraphQL services is graphql.org, and howtographql.com offers an excellent set of resources for popular web development stacks.