GraphQL

Facebook started GraphQL development in 2012 and released a draft specification and reference implementation as open source in 2015.{{cite web|url=https://code.fb.com/core-data/graphql-a-data-query-language/|title=GraphQL: A data query language|date=14 September 2015}} In 2018, GraphQL was moved to the newly established GraphQL Foundation, hosted by the non-profit Linux Foundation.{{Cite news|url=https://techcrunch.com/2018/11/06/facebooks-graphql-gets-its-own-open-source-foundation/|title=Facebook's GraphQL gets its own open-source foundation|work=TechCrunch|access-date=2018-11-07|language=en-US}}{{Cite news|url=https://www.linuxfoundation.org/press/press-release/intent_to_form_graphql|title=The Linux Foundation Announces Intent to Form New Foundation to Support GraphQL |date=2018-11-06|work=The Linux Foundation|access-date=2023-03-17|language=en-US}}

On February 9, 2018, the GraphQL Schema Definition Language became part of the specification.{{cite web|url=https://github.com/facebook/graphql/pull/90/|title=GraphQL SDL included in Github repository|website=GitHub }}

Many popular public APIs adopted GraphQL as the default way to access them. These include public APIs of Facebook, GitHub, Yelp, Shopify, Google Directions API and many others.{{cite web |date=5 July 2025 |title=GraphQL Landscape |url=https://landscape.graphql.org/ |website=landscape.graphql.org}}{{Citation |title=graphql-kit/graphql-apis |date=2025-05-31 |url=https://github.com/graphql-kit/graphql-apis |access-date=2025-06-05 |publisher=graphql-kit}}

GraphQL supports reading, writing (mutating), and subscribing to changes to data (realtime updates – commonly implemented using WebSockets).{{cite web |title=GraphQL |url=https://facebook.github.io/graphql/June2018/#sec-Language.Operations |website=facebook.github.io |publisher=Facebook |access-date=4 July 2018 |archive-url=https://web.archive.org/web/20180718051011/http://facebook.github.io/graphql/June2018/#sec-Language.Operations |archive-date=18 July 2018 |url-status=dead }} A GraphQL service is created by defining types with fields, then providing functions to resolve the data for each field. The types and fields make up what is known as the schema definition. The functions that retrieve and map the data are called resolvers.{{Cite web |title=Introduction to GraphQL |url=https://graphql.org/learn/ |access-date=2023-04-25 |website=graphql.org}}

After being validated against the schema, a GraphQL query is executed by the server. The server returns a result that mirrors the shape of the original query, typically as JSON.{{Cite web |title=Execution |url=https://graphql.org/learn/execution/ |access-date=2023-04-25 |website=graphql.org}}

File:Schema of graphql-swapi API rendered as a graph.png]

With GraphQL, you model your business domain as a graph by defining a schema; within your schema, you define different types of nodes and how they connect/relate to one another.{{Cite web |title=Thinking in Graphs {{!}} GraphQL |url=https://graphql.org/learn/thinking-in-graphs/#its-graphs-all-the-way-down |access-date=2025-06-03 |website=graphql.org |language=en}}

The GraphQL type system describes what data can be queried from the API. The collection of those capabilities is referred to as the service’s schema and clients can use that schema to send queries to the API that return predictable results.{{Cite web |title=Schemas and Types {{!}} GraphQL |url=https://graphql.org/learn/schema/ |access-date=2025-06-03 |website=graphql.org |language=en}}

The root type of a GraphQL schema, {{code|Query}} by default, contains all of the fields that can be queried. Other types define the objects and fields that the GraphQL server can return. There are several base types, called scalars, to represent things like strings, numbers, and IDs.

Fields are defined as nullable by default, and a trailing exclamation mark can be used to make a field non-nullable (required). A field can be defined as a list by wrapping the field's type in square brackets (for example, {{code|authors: [String]}}).{{Cite web |title=GraphQL |url=https://spec.graphql.org/October2021/ |access-date=2023-04-25 |website=spec.graphql.org}}

type Query {

currentUser: User

}

type User {

id: ID!

name: String!

}

A GraphQL query defines the exact shape of the data needed by the client.

query CurrentUser {

currentUser {

name

age

}

}

Once validated and executed by the GraphQL server, the data is returned in the same shape.

{

"currentUser": {

"name": "John Doe",

"age": 23

}

}

A GraphQL mutation allows for data to be created, updated, or deleted. Mutations generally contain variables, which allow data to be passed into the server from the client. The mutation also defines the shape of the data that will be returned to the client after the operation is complete.

mutation CreateUser($name: String!, $age: Int!) {

createUser(userName: $name, age: $age) {

name

age

}

}

The variables are passed as an object with fields that match the variable names in the mutation.

{

"name": "Han Solo",

"age": 42

}

Once the operation is complete, the GraphQL server will return data matching the shape defined by the mutation.

{

"data": {

"createUser": {

"name": "Han Solo",

"age": 42

}

}

}

GraphQL also supports live updates sent from the server to client in an operation called a subscription. Again, the client defines the shape of the data that it needs whenever an update is made.

subscription {

newPerson {

name

age

}

}

When a mutation is made through the GraphQL server that updates the associated field, data is sent to all subscribed clients in the format setup through the subscription.

{

"newPerson": {

"name": "Jane",

"age": 23

}

}

While there’s nothing that prevents a GraphQL service from being versioned just like any other API, GraphQL takes a strong opinion on avoiding versioning by providing the tools for the continuous evolution of a GraphQL schema.{{Cite web |title=Schema Design {{!}} GraphQL |url=https://graphql.org/learn/schema-design/#versioning |access-date=2025-06-03 |website=graphql.org |language=en}}

The @deprecated built-in directive is used within the type system definition language to indicate deprecated portions of a GraphQL service’s schema, such as deprecated fields on a type or deprecated enum values.

GraphQL only returns the data that’s explicitly requested, so new capabilities can be added via new types or new fields on existing types without creating a breaking change. This has led to a common practice of always avoiding breaking changes and serving a versionless API.

GraphQL does not provide a full-fledged graph query language such as SPARQL, or even in dialects of SQL that support transitive closure. For example, a GraphQL interface that reports the parents of an individual cannot return, in a single query, the set of all their ancestors.

GraphQL APIs can be tested manually or with automated tools issuing GraphQL requests and verifying the correctness of the results. Automatic test generation is also possible.{{Cite journal |last1=Vargas |first1=D. M. |last2=Blanco |first2=A. F. |last3=Vidaurre |first3=A. C. |last4=Alcocer |first4=J. P. S. |last5=Torres |first5=M. M. |last6=Bergel |first6=A. |last7=Ducasse |first7=S. |date=2018 |title=Deviation Testing: A Test Case Generation Technique for GraphQL APIs |journal=11th International Workshop on Smalltalk Technologies (IWST) |pages=1–9 }} New requests may be produced through search-based techniques due to a typed schema and introspection capabilities.{{Cite book |last1=Karlsson |first1=Stefan |last2=Causevic |first2=Adnan |last3=Sundmark |first3=Daniel |title=2021 IEEE/ACM International Conference on Automation of Software Test (AST) |chapter=Automatic Property-based Testing of GraphQL APIs |date=May 2021 |chapter-url=https://ieeexplore.ieee.org/document/9463000 |location=Madrid, Spain |publisher=IEEE |pages=1–10 |doi=10.1109/AST52587.2021.00009 |arxiv=2012.07380 |isbn=978-1-6654-3567-3|s2cid=229156477 }}

Some of the software tools used for testing GraphQL implementations include Postman, GraphiQL, Apollo Studio, GraphQL Hive, GraphQL Editor, and Step CI.{{multiref2|{{Citation |title=GraphQL IDE Monorepo |date=2023-04-25 |url=https://github.com/graphql/graphiql/blob/aeedf7614e422c783f5cfb5e226c5effa46318fd/packages/graphiql/README.md |access-date=2023-04-25 |publisher=GraphQL}}|{{Cite web |title=The Apollo Studio Explorer |url=https://www.apollographql.com/docs/graphos/explorer/ |access-date=2023-04-25 |website=Apollo Docs}}|{{Cite web |title=GraphQL Editor API Console |url=https://graphqleditor.com/docs/graphql-editor/api/ |access-date=2023-09-02 |website=GraphQL Editor Docs}}|{{Cite web |title=Testing GraphQL APIs |url=https://docs.stepci.com/guides/testing-graphql.html |access-date=8 January 2023 |website=Step CI Documentation}}

}}[https://the-guild.dev/graphql/hive/docs/dashboard/laboratory "Hive Laboratory"]. Hive Documentation. Retrieved 26 November 2024.

• Query by Example
• OpenAPI Specification
• Microservices

{{reflist}}

• {{Official website|https://graphql.org}}
• {{YouTube|783ccP__No8|GraphQL: The Documentary}}

{{Query languages}}

{{Web interfaces}}

Category:Query languages

Category:Data modeling languages

Category:Graph data structures

Category:Software architecture