Skeptics often describe GraphQL as something only facebook-sized companies need, something complicated, or feel that its most talked-about features, such as asking exactly for the fields you need or unversioned APIs are not that useful or can already be done with REST.
I do not agree with this. In my experience, the main strength of GraphQL is that it allows developers to do the same things as with REST, but more easily, faster, and with better tooling.
So what things do we want when writing or using an API?
-
Input and output validation: I want to describe my input and output in an easy-to-use DSL, and have them properly typed in my code.
-
Add routes easily: The less boilerplate the better
-
Typed API clients: Writing frontend code in TypeScript is hugely useful. You don’t want to write the types yourself or, worse, use the
anytype. -
API documentation and an easy way to try out the queries
-
A way to ask (or not) for expensive or heavy data
Most of the above can be done with a REST API, however, the tooling can be bad or even absent, or the solutions overly complicated. GraphQL comes out of the box with good solutions for all of these, for example:
-
Input and output validation: Many REST frameworks ask for JSON-schema or OAS schemas in JSON or YAML format. GraphQL has an easy-to-use and remember DSL.
-
Typed API clients: If you want a typed client for an existing API, you’ll most likely need to generate a client from an OAS schema. The official generator’s TypeScript plugin hasn’t been updated in four years and doesn’t always generate valid modern TypeScript, and the alternative ones don’t support all of the OAS features. With GraphQL, GraphQL Code Generator works perfectly.
-
API documentation and an easy way to try out the queries: GraphiQL, the official-ish has auto-completion, syntax highlighting and plenty of other features
-
A way to ask (or not) for expensive or heavy data: One of the selling points of GraphQL and something that can’t be done at all in a REST API if you want type safety and flexible queries.
Yeah, but GraphQL is more complicated
Not really:
-
It’s a text-based protocol. Responses are normal JSON objects. Queries are JSON objects with a
queryentry. You don’t have to use a client. You can usecurl, you can usefetch. -
Client-side, you can use GraphQL exactly like a REST API, just with more flexible queries. Large clients such as Apollo are more complicated, but that’s because they have more features.
-
Server-side is the most complicated, but once you know how a query is dispatched to resolvers, you know 90% there is to know.
Closing thoughts
Resources about GraphQL insist on “advanced” features such as the “graph” part, error handling, API versioning, or federation. I think this does GraphQL a disservice and is part of the reason people think it is useful only for facebook-like companies. Although the advanced features can be useful, where GraphQL shines the most is in making the simple, everyday things that are needed in every API easier.