GraphQL, explained
GraphQL was developed at Facebook in 2012 and open-sourced in 2015; it is now governed by the GraphQL Foundation. A server publishes a strongly typed schema of types, fields, queries, mutations and subscriptions, and clients send queries that mirror the shape of the response they want.
query {
invoice(id: "inv_123") {
amount
currency
customer { email }
}
}Because clients choose their fields, GraphQL avoids the over-fetching and under-fetching common with fixed REST responses, and one request can replace several round trips. The trade-offs are harder HTTP caching, the need to limit query depth and cost, and errors that often arrive with a 200 OK status inside an errors array.
GraphQL APIs are usually evolved without URL versions: fields are marked @deprecated and removed later. Removing a field, changing its type or making an argument required is still a breaking change for any client whose queries use it. See REST vs GraphQL for when each fits.
Related terms
- REST API: A REST API is an HTTP API organised around resources identified by URLs and manipulated with standard methods such as GET, POST, PUT, PATCH and DELETE.
- gRPC: gRPC is an open-source remote procedure call framework that uses HTTP/2 and Protocol Buffers to let services call typed methods on each other efficiently.
- API: An API (application programming interface) is a defined contract that lets one piece of software request data or actions from another without knowing how it is implemented.
- API deprecation: API deprecation is the formal announcement that an endpoint, field or version is going away, with a timeline for clients to migrate before it is removed.