Definition

GraphQL is a data query language developed internally by Facebook and publicly released in 2015. Historically Facebook tried to solve the following problem:

We were frustrated with the differences between the data we wanted to use in our apps and the server queries they required. GraphQL was our opportunity to rethink mobile app data-fetching from the perspective of product designers and developers. It moved the focus of development to the client apps, where designers and developers spend their time and attention. GraphQL, a data query language. Post by Lee Byron

Graphically the idea can be represented as:

The main Facebook driver in the language design was an idea: ==What you want is what you get==

Other problems that GraphQL is supposed to solve

1. Efficiency ↑:
   • Receive only required data to save throughput and battery on mobile devices.
   • RESTful service may require multiple round-trips (resource-intensive on mobile networks) or a complex join statement in SQL
2. Development cost / Modifiability ↑:
   • Sometimes it is necessary only shrink the response or combine two results in one => no need to create a new REST API.
   • Typically higher cost of any changes in RESTful web services.
   • Higher cost for API versioning support for REST.
   • One request/manipulate language instead of variety of technologies (REST, SOAP, etc.) => less required knowledge for client developers.
3. Time to market ↑:
   • Development is moved more to the side of API consumers.
   • Easier to create a mashup, release and optimize later.
   • Typically different speed between front-end/mobile developers and back-end developers.

Drawbacks

Since GraphQL is, in fact, an additional layer of abstraction then it inherits all drawbacks of that pattern:

1. Performance ↓:

   • Potentially performance issues due to another layer if implementation.
   • Because GraphQL may sit on top of different by nature sources the caching on GraphQL-layer might be not safe.

2. Testability ↓:

   • When a new bug occurs it is not clear on which layer the cause is: source, GraphQL server or resolver implementation.

Additionally, the initial GraphQL drivers “the desire to load all information in a single round trip” and “let API consumers access all the information " bring to other drawbacks:

1. Modifiability ↓:
   • GraphQL does not offer information hiding => It also creates a strong coupling between the API provider and all its clients. If the data model changes in some way, all the API clients will have to update their code in numerous places.
   • No explicit versioning brings to difficulties for consumers to get to know that some elements of API is not more supported and even already has been deleted.

Other issues with the current GraphQL design (may be fixed in future) are:

1. In comparison with REST, names for any manipulation operation should be explicitly defined, while it REST it is obvious: DELETE for а delete, PATCH - for an update etc.
2. In comparison with REST GraphQL always returns 200 and error response, it is less obvious then REST 404 for example.
3. GraphQL focuses on data and not actions: querying and mutation are disconnected

When NOT to use

1. HTTP caching is a pillar of good performance in the system, GraphQL will require а huge increase in computation resources because it doesn’t support caching.
2. There is a really good compact REST API ⇨ GraphQL will an additional complexity with loosing of several REST advantages like caching, versioning.
3. There is a poor REST API backend and GraphQL is kind of there is an attempt to improve it ⇨ all the problems like bugs, poor splitting concerns, bad performance will simply get bigger and they bring to a buggy, slower, unstable GraphQL middleware.
4. There is an existing bad REST API that was built without an understanding of тхэ real use cases and GraphQL is an attempt to resolve it through a combination of a lot of REST request and complicated business logic ⇨ GraphQL is not ETL/ESB!
5. There are no thick clients (browser or mobile) or a consumer is only one application/client ⇨ no one will utilize all the flexibility of GraphQL.
6. When no one cares about API documentation and as a result, no one will care of GraphQL API documentation as well, which brings again to a state when no one uses GraphQL API.
7. If there is a well-established API pricing model with good profit, then GraphQL API pricing might be not so efficient and easy to define and as result significantly underpriced which could lead to business loss.