A specification for GraphQL, a query language and execution engine for APIs that enables clients to request exactly the data they need.
GraphQL is a query language and execution engine for APIs that allows clients to request exactly the data they need from a server. It provides a strongly typed schema to define the capabilities of an API and enables declarative data fetching, eliminating common issues like over-fetching or under-fetching of data. The GraphQL specification serves as the official standard that implementations must follow to ensure consistency and interoperability across different programming languages and frameworks.
This specification is primarily for developers and teams building their own GraphQL implementations, tools, or servers, rather than end-client developers consuming GraphQL APIs.
Developers choose GraphQL because it offers a more efficient and flexible alternative to REST, with built-in validation, introspection, and a type system that serves as clear API documentation. Its specification ensures that implementations are consistent and interoperable across ecosystems.
GraphQL is a query language and execution engine tied to any backend service.
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
Clients request exact data shapes, eliminating over-fetching and under-fetching, as demonstrated in the Star Wars example queries like HeroNameQuery.
The type system serves as an API contract, enabling static validation and clear documentation, detailed in the spec's type system section with Human and Droid types.
Schemas can be queried via introspection (e.g., __schema field), allowing for auto-generated documentation and rich IDE support, as shown in the introspection examples.
Queries mirror response data hierarchically, making them predictable and easy to nest, exemplified in the NestedQuery with fragments.
Building a spec-compliant server requires handling execution, validation, and introspection, which adds complexity compared to simpler REST frameworks.
GraphQL often uses POST requests for queries, bypassing HTTP caching mechanisms, making it harder to optimize compared to REST's URL-based caching.
Evolving APIs without breaking changes requires careful versioning and deprecation strategies, which can be cumbersome for fast-moving projects.