Why it is needed
- Declarative. Query responses are decided by the client rather than the server. A GraphQL query returns exactly what a client asks for and no more.
- Compositional. A GraphQL query itself is a hierarchical set of fields. The query is shaped just like the data it returns. It is a natural way for product engineers to describe data requirements.
- Strong-typed. A GraphQL query can be ensured to be valid within a GraphQL type system at development time allowing the server to make guarantees about the response. This makes it easier to build high-quality client tools. It obviates the need for repetitive and error-prone code to shuffle raw, untyped JSON into strongly-typed business objects.
- Backwards Compatible: In a world of deployed native mobile applications with no forced upgrades, backwards compatibility is a challenge. Facebook, for example, releases apps on a two week fixed cycle and pledges to maintain those apps for at least two years. This means there are at a minimum 52 versions of our clients per platform querying our servers at any given time. Client-specified queries simplifies managing our backwards compatibility guarantees.
REST, an acronym for Representational State Transfer, is an architectural style rather than a formal protocol.
A number of weaknesses in typical REST systems:
- Fetching complicated object graphs require multiple round trips between the client and server to render single views.
- Over-fetching. Invariably, fields and additional data are added to REST endpoints as the system requirements change. However, old clients also receive this additional data as well, because the data fetching specification is encoded on the server rather than the client.
- one solution is to overlay a versioning system onto the REST endpoints. Versioning also complicates a server, and results in code duplication, spaghetti code, or a sophisticated, hand-rolled infrastructure to manage it.
- Another solution to limit over-fetching is to provide multiple views – such as “compact” vs “full” – of the same REST endpoint. However, this coarse granularity often does not offer adequate flexibility.
- REST endpoints are usually weakly-typed and lack machine-readable metadata.
- Many of these attributes are linked to the fact that “REST is intended for long-lived network-based applications that span multiple organizations” according to its inventor. This is not a requirement for APIs that serve a client app built within the same organization.
vs Ad Hoc Endpoints
- Entropic server codebases. These systems typically define a custom endpoint per view. For systems with a wide surface area this can quickly grow into a maintenance nightmare of orphaned endpoints, inconsistent tooling, and massive server code duplication.
- Much like REST, the payloads of custom endpoints grow monotonically (even with mitigation from versioning systems) as the server evolves.
GraphQL represents a novel way of structuring the client-server contract.
Servers publish a type system specific to their application, and GraphQL provides a unified language to query data within the constraints of that type system. That language allows product developers (e.g. the advanced FE developers) to express data requirements in a form natural to them: a declarative and hierarchal one.