GraphQL is a data query language for APIs that was developed internally by Facebook and made public in 2015. It provides an interesting alternative to REST and ad-hoc endpoints, looking to overcome the inherent limitations of each.

For example, the pseudo code below outlines a basic REST endpoint.

/v3/users?id=1  

{
  "id": 1,  
  "name": "Matt",  
  "title": "Enterprise IT Architect",  
  "orders": [  
    "/v3/orders?id=123",  
    "/v3/orders?id=1234",
    ...
  ]  
}


As you can see, the details of each specific order are made available via additional endpoints. Therefore, to be able to retrieve the details of multiple orders, multiple requests must be sent, which can be slow and unreliable.

To overcome this challenge, it is not uncommon to create an ad-hoc endpoint, which is pre-configured to serve the full data request (removing the need for multiple requests). However, this requires foresight regarding the specific data requests and the creation of a server-side, ad-hoc endpoint, therefore adding complexity to the application and increasing the support overhead.

GraphQL takes a different approach, instead of defining the structure of responses on the server, the flexibility is given to the client. To achieve this, GraphQL provides a thin-layer that sits in front of the application, where a GraphQL Schema is created, which describes the data. The schema is then accessed via a single endpoint, allowing other applications to send specific queries.

The characteristics and benefits of GraphQL are summarised below:

  • A GraphQL query is expressive and targeted, returning predictable, specific results.

  • A GraphQL query is not limited to the properties of one resource, removing the need for multiple requests.

  • A GraphQL API is organised in terms of types and fields, not endpoints. This supports discoverability and accuracy (through suggestions), as well as provides clear and helpful errors.

  • A GraphQL API provides access to the full capabilities of the data from a single endpoint (via types and fields).

  • The ability to add new fields and types to the GraphQL API without impacting existing queries. This enables a single evolving version, instead of needing to maintain multiple versions.

  • GraphQL creates a unified API across the entire application and is limited by a specific language or storage architecture.

  • GraphQL provides powerful developer tools, such as GraphiQL, which streamline the development process, reduce errors and encourages an active ecosystem.

Linked below is a great video from Steven Luscher from Facebook, who demonstrates how to get started with GraphQL across Python, Ruby and Node.

I believe the video clearly demonstrates the power, flexibility and potential of GraphQL. As a result, I predict to see the use of GraphQL increase rapidly over the coming years, potentially displacing REST.

development programming api graphql rest