Intro to GraphQL

GraphQL is a query language for APIs and a server-side runtime for executing those queries. A GraphQL query is interpreted by the server and returns data in a format specified by the server's GraphQL schema.

Here is an example query:

query {
  user {
    firstName
    lastName
  }
}

...which would result in a response like so:

{
  "data": {
    "user": {
      "firstName": "John",
      "lastName": "Doe"
    }
  }
}

GraphQL vs. REST

GraphQL attempts to package solutions for a variety of challenges that are often encountered with REST APIs.

Get many resources in a single request

GraphQL provides the ability to access not only the properties of a single resource but also all of its related resources in a single query. It additionally allows multiple queries to be provided in a single request to the server. In most REST APIs, it can take several requests to the server to get all of the data needed for your application. With GraphQL, you can get all of the data you need in a single request.

This can help simplify and speed up your integration with the API.

Describe what's possible with a typed schema

GraphQL APIs are described in publicly accessible schemas in terms of types and fields rather than endpoints. With GraphQL, there is a single endpoint provided which interprets your queries. GraphQL uses types to validate that queries are properly formed and to describe to the client (you) what format to expect resulting data to be in.

This can help provide clearer and more helpful errors when using the API while also avoiding the need to guess at what the data format should be.

Get only the data you want

GraphQL queries must explicitly specify what data the API should return from a query. This allows APIs to evolve without impacting your application and ensures that the results from the API are in a predictable format for your application.

In standard REST APIs, all of the possible data that a client might want to use gets include in every response. This creates poorly optimized requests if all your application is interested in is one field from the response.

This can help improve the speed of the queries and stabilizes the APIs since the client controls the format of the response, not the server.

Documentation as a first-class citizen

GraphQL schemas are used to both drive server-side runtime behavior and also describe to clients what fields and types are available to use. By tying the two together, documentation within the Schema remains in sync as changes are made to the backend.

GraphQL also provides support for powerful tools like GraphiQL which leverage these schemas and surface the documentation.

This can help ensure documentation remains up-to-date.

API evolution without API versioning

GraphQL uses an evolution versioning system rather than a semantic versioning system. This means that clients do not need to worry about updating to new version numbers as the API changes. Instead, the schema can evolve over time with new types, allowing types that are still being queried to be used.

This allows the provider to release new features without impacting existing clients.

Resources

There are many resources available to learn more about GraphQL. Here are some resources we've found to be the best place to start: