GraphQL

The latest draft specification can be found at which tracks the latest commit to the main branch in this repository. Previous releases of the GraphQL specification can be found at permalinks that match their release tag. For example, If you are linking directly to the GraphQL specification, it's best to link to a tagged permalink for the particular referenced version. The target audience for this specification is not the client developer, but those who have, or are actively interested in, building their own GraphQL implementations and tools. In order to be broadly adopted, GraphQL will have to target a wide variety of backend environments, frameworks, and languages, which will necessitate a collaborative effort across projects and organizations. This specification serves as a point of coordination for this effort. GraphQL consists of a type system, query language and execution semantics, static validation, and type introspection, each outlined below. To guide you through each of these components, we've written an example designed to illustrate the various pieces of GraphQL. This example is not comprehensive, but it is designed to quickly introduce the core concepts of GraphQL, to provide some context before diving into the more detailed specification or the GraphQL.js reference implementation. The premise of the example is that we want to use GraphQL to query for information about characters and locations in the original Star Wars trilogy. For our Star Wars example, the starWarsSchema.ts file in GraphQL.js defines this type system. This shorthand is convenient for describing the basic shape of a type system; the JavaScript implementation is more full-featured, and allows types and fields to be documented. It also sets up the mapping between the type system and the underlying data; for a test case in GraphQL.js, the underlying data is a set of JavaScript objects, but in most cases the backing data will be accessed through some service, and this type system layer will be responsible for mapping from types and fields to that service. Since we're talking about the Star Wars trilogy, it would be useful to describe the episodes in which each character appears. To do so, we'll first define an enum, which lists the three episodes in the trilogy: Now we have two types! Let's add a way of going between them: humans and droids both have friends. But humans can be friends with both humans and droids. How do we refer to either a human or a droid? If we look, we note that there's common functionality between humans and droids; they both have IDs, names, and episodes in which they appear. So we'll add an interface, Character , and make both Human and Droid implement it. Once we have that, we can add the friends field, that returns a list of Character s. Note that while in our current implementation, we can guarantee that more fields are non-null (since our current implementation has hard-coded data), we didn't mark them as non-null. One can imagine we would eventually replace our hardcoded data with a backend service, which might not be perfectly reliable; by leaving these fields as nullable, we allow ourselves the flexibility to eventually return null to indicate a backend error, while also telling the client that the error occurred. We're missing one last piece: an entry point into the type system. When we define a schema, we define an object type that is the basis for all query operations. The name of this type is Query by convention, and it describes our public, top-level API. Our Query type for this example will look like this: In this example, there are three top-level operations that can be done on our schema: hero returns the Character who is the hero of the Star Wars trilogy; it takes an optional argument that allows us to fetch the hero of a specific episode instead. human accepts a non-null string as a query argument, a human's ID, and returns the human with that ID. droid does the same for droids. These fields dem