Rest vs GraphQL from a developer perspective

Definitions

Photo by Joshua Sortino on Unsplash
  • REST — is an acronym for REpresentational State Transfer. It is an architectural style for distributed hypermedia systems and was first presented by Roy Fielding in 2000 in his famous dissertation. It helps expose resources via HTTP methods like POST, PUT, DELETE, HEAD, PATCH, GET, etc…
  • GraphQL — is a query language for APIs. Its main purpose is to provide an easy and convenient way to describe your data, ask for what you want, get a predictable result.

REST Pros

  • Scalability.
  • Caching — for instance in a blog API example, when a client wants to query for article x, that request and data will be consistent for every client. The data being returned can be cached on the server side for subsequent API requests, which can reduce database load and speed up the API response time.
  • Rate limits — the number of requests tied to a user API key or IP.
  • HATEOAS (hypermedia controls).
  • High performance due to HTTP2.
  • Works with any representation.
  • Server-driven application state (server tells you what you can call and when).
  • Full decoupling of client and server enabling the independent evolution.
  • Can fit in any architecture design with few tweaks.

REST Cons

  • Requires clients to play along.
  • Many network requests due to may endpoints.
  • Deprecation can be at times a headache. In that case, you have to rely on versioning.
  • Standards for enforcing strong typing are fragmented.
  • Weaker typing means more boilerplate code on consuming systems to “reshape”, and also potentially boilerplate on the server to expose “one-off” routes to pre-consolidate or transform data for consumers.
  • Operations like searching, dealing with large data sets and working with binary files can all break the clean and organised feel of any REST API.
  • Over and under fetching data.

GraphQL Pros

  • Network performance improvements. You can request for the exact data that you need and in one network roundtrip (theoretically).
  • Loose coupling between client and server.
  • Developer Tooling.
  • Strong Typing.
  • Reduce version-breaking changes that can happen when resources and data schemas change in a REST API.
  • The mental model for integration becomes “what data/operations do I need” (declarative) vs “how do I get at the data/operations that I need” (imperative).
  • A standard way to expose data and operations.
  • Support for real-time data.
  • A fast-growing community that supports most modern front-end web frameworks and libraries.
  • Can be added gradually to an existing service layer.
  • Abstraction of complexity — As your data set grows and you optimise your database schema in ways that don’t follow traditional resource-driven REST design, GraphQL will abstract this complexity and allow clients to interact with the changing data set in a consistent and predictable way.
  • Requesting this data can be done in a much more programmatic way, allowing the client to query for the exact information they need.

GraphQL Cons

  • Opting into complexity on the server-side.
  • Some data schemas aren’t elegantly represented as a graph, which may lead to awkward implementations.
  • Opinionated towards JavaScript-based systems, though there are implementations on other platforms.

Conclusion

At a high level, GraphQL is an excellent design choice when your application’s data structure requires a large number of queries like filtering within a REST API.

REST is also a perfect choice for highly structured data sets and applications, where the actions being performed on the API follow a predictable pattern. Creating, reading, updating and deleting distinct resources within the API are all actions that make sense in a REST context.