As we harden our types, expect minimal but possibly breaking changes.
From the wonderful How to GraphQL series:
GraphQL is a new API standard that provides a more efficient, powerful and flexible alternative to REST. It was developed and open-sourced by Facebook and is now maintained by a large community of companies and individuals from all over the world.
At its core, GraphQL enables declarative data fetching where a client can specify exactly what data it needs from an API. Instead of multiple endpoints that return fixed data structures, a GraphQL server only exposes a single endpoint and responds with precisely the data a client asked for.
GraphQL and REST are both kinds of APIs. In many ways, they solve similar problems. But let's focus on the comparative differences for a moment. Three critical points of difference:
With REST, exposing API functionality requires developers to implement complicated "hypermedia" patterns. Most of the time, however, REST APIs simply do not expose functionality in automated ways. In contrast, GraphQL lets API consumers download a schema -- a complete representation of all of the functionality made available by the API. GraphQL APIs therefore offer strong predictability, which means fewer bugs!
GraphQL provides built-in ways of documenting API features via a field type called
describe. Practically speaking, this means that every object in the system, and all of its fields, contain rich, navigable, plain-language descriptions of its functionality. This includes fields where the values might be one of a specific list (say, one of the currencies supported by Universe, or the state of an
order). A richly documented, navigable API means developer friendliness and faster development times.
In the REST paradigm, it's very typical to need to gather data by accessing multiple endpoints. For example, perhaps we have an
/orders/<id> endpoint to fetch
order data. An
order might have a relationship to an object called
ticket. We might represent access to that relationship at
/orders/<id>/tickets. There might also be a
buyer belonging to each
order, available at
/orders/<id>/buyer. We might need to make three separate requests to collect the information we need. In GraphQL, this is unnecessary - we can make a single request to the server, for exactly the data we need - including relationships. This means fewer network requests, and so faster apps.
GraphQL provides self-documenting interfaces; docs are automatically generated and the developer can provide inline comments of types for more verbosity. This also gives the ability for client apps to generate the schema and never have to provide models or type definitions of their own.
GraphQL standardizes API responses, so every response is of the same format. This improves error handling, response parsing, paginated endpoints, etc.
GraphQL solves the expensive endpoint problem, more specifically slow side loading of unneeded data. With a complex architecture of data, there exists a lot of associations creating unnecessary joins and slowing queries down. GraphQL provides specifications and conventions for arguments, connections between objects (relationships), variables, fragments (for query compostability) to make sure only needed data is returned and returned fast.
Finally, GraphQL provides a way for Universe to abstractly layer over new interfaces into our existing data structures. It gives us a fresh conceptual start so we can make sure the data associations make sense to the developer without having to explain internal legacy naming.