GraphQL is a query language for your API, as well as a server-side runtime for executing queries based on the type system you define for your data. The GraphQL protocol is not dependent on any specific database or storage engine and is backed by your existing code and data instead.
Predefined request and response
Send a GraphQL query to your API and get exactly what you need, nothing more and nothing less. GraphQL queries always return predictable results. Apps using GraphQL are fast and stable because they control the data they get, not the server.
GraphQL queries access not just the properties of one resource but also smoothly follow references between them. While typical REST APIs require loading from multiple URLs, GraphQL APIs get all the data your app needs in a single request. Apps using GraphQL can be quick even on slow mobile network connections.
Types and fields
GraphQL APIs are organized by types and fields, not by endpoints. One endpoint provides access to all your data capabilities. GraphQL uses types to ensure Apps only ask for what’s possible and provide clear and helpful errors. Apps can use types to avoid writing manual parsing code.
Queries and Mutation
At its simplest, GraphQL is about asking for specific fields on objects. Let's start by looking at a very simple query and the result we get when we run it:
In the previous example, we just asked for the name of our hero which returned a String, but fields can also refer to Objects. In that case, you can make a sub-selection of fields for that object. GraphQL queries can traverse related objects and their fields, letting clients fetch lots of related data in one request, instead of making several roundtrips as one would need in a classic REST architecture.
Most discussions of GraphQL focus on data fetching, but any complete data platform needs a way to modify server-side data as well.
In REST, any request might end up causing some side-effects on the server, but by convention it's suggested that one doesn't use GET requests to modify data. GraphQL is similar - technically any query could be implemented to cause a data write. However, it's useful to establish a convention that any operations that cause writes should be sent explicitly via a mutation.
Just like in queries, if the mutation field returns an object type, you can ask for nested fields. This can be useful for fetching the new state of an object after an update. Let's look at a simple example mutation:
Efficient developer tools
Know exactly what data you can request from your API without leaving your editor, highlight potential issues before sending a query, and take advantage of improved code intelligence. By leveraging your API's type system, GraphQL makes it easy to build powerful tools.
Customize data and code
In contrast to a specific storage engine, GraphQL creates a uniform API across your entire application. Write GraphQL APIs that leverage your existing data and code with GraphQL engines available in a wide range of languages. You provide functions for each field in the type system, and GraphQL calls them with optimal concurrency.