Introduction to GraphQL

Learn about GraphQL, how it works, and how to use it

GraphQL is a query language for your API, and a server-side runtime for executing queries using a type system you define for your data. The GraphQL specification was open-sourced in 2015 and has since been implemented in a variety of programming languages. GraphQL also isn’t tied to any specific database or storage engine and is instead backed by your existing code and data.

Describe your API with a type system

A GraphQL service is created by defining types and their fields, and then writing functions that provide data for each field. For example, a GraphQL service that tells you the name of a logged-in user might look like this:

type Query {
  me: User
}
 
type User {
  name: String
}

Along with functions for each field on each type:

Query: {
  me(obj, args, context, info) {
    return context.request.auth.user
  }
}
 
User: {
  name(obj, args, context, info) {
    return context.db.getUserFullName(obj.id)
  }
}

In the example above, the function that provides data for the me field on the Query type uses information about the authenticated user who made the request, while the the name field on the User type is populated by using that user’s ID to fetch their full name from an existing database.

Query exactly what you need

After a GraphQL service is running (typically at a URL on a web service), it can receive GraphQL queries to validate and execute from clients. The service first checks a query to ensure it only refers to the types and fields defined for the API and then runs the provided functions to produce a result.

For example, the query:

{
  me {
    name
  }
}

Could produce the following JSON result:

{
  "data": {
    "me": {
      "name": "Luke Skywalker"
    }
  }
}

With even a simple query, we can see some of the key features that make GraphQL so powerful. The client can make queries to the API that mirror the structure of the data that they need and then receive just that data in the expected shape with a single request—and without having to worry about what underlying data sources provided it.

Evolve your API without versioning

Client requirements change over time and GraphQL allows your API to evolve in response to those needs and without the overhead of managing different API versions. For example, if a new feature calls for more specific name values to be available, then the User type could be updated as follows:

type User {
  fullName: String
  nickname: String
  name: String @deprecated(reason: "Use `fullName`.")
}

GraphQL will continue to provide data as expected for the deprecated name field until it’s determined that clients have updated their existing queries and the older field can be safely removed.

Try it out!

The best way to learn GraphQL is to start writing queries. The query editors used throughout this guide are interactive, so try adding an id and appearsIn fields to the hero object to see an updated result:

Next steps

Now that you know some key GraphQL concepts, you’re ready to learn about all of the different aspects of its type system.

If you’re already familiar with GraphQL and would like to read documentation on how to build a GraphQL service, then there are libraries to help you implement GraphQL in many different languages. There are also many libraries available that allow client applications to query existing GraphQL APIs.

For an in-depth learning experience with practical tutorials, see the available training courses.