A REST View of GraphQL

  1. What does the REST architectural style mean?
  2. How has REST been implemented in practice?
  3. What is GraphQL? What problems does it solve?
  4. How is GraphQL incompatible with REST?

What is REST?

The REST architectural style

  1. Websites: Programs that serve content for humans to consume and interact with on a browser.
  2. Browsers: Programs meant for (mostly) humans to interact with websites.
  3. API Service Providers: Programs meant to enable other programs to consume and interact with data
  4. API Clients: Programs written to consume and interact with data from an API Service Provider.
  1. Each utility should run as a standalone process
  2. Communication between utilities is done only using stdin and stdout via a text interface
  1. Simplicity: Easy for a newcomer to use utilities together
  2. Re-usability: Allows mixing and matching any two utilities if the second can process the data from the first. For example, I can pipe the output from cat or ls or ps to grep. The author of grep does not worry about where the input is coming from.
  • Use the client/server pattern for communication
  • Keep the server stateless by having each request send everything required to process that request.
  • Responses to requests must be labelled as cacheable or not
  • Uniform interface
  • Servers must expose resources with unique IDs
  • Resources must be retrieved and manipulated using representations (media-types)
  • Requests and responses must have all the information to be able to interpret them, i.e they must be self-descriptive
  • Hypermedia as the engine of application state (HATEOAS): Clients must rely only on the response to a request to determine the next steps that can be taken. There must be no out-of-band communication related to this.
  • Layered system: Each component in a system must only rely on the behaviour of systems it immediately interacts with.
  • Code on demand: This is an optional constraint. A server can send code to be executed by the client to extend the functionality of the client (JavaScript, for example).

REST in Practice

What is GraphQL?

# Our schema consists of products, users and orders. We will first define these types and relationships type Product { id: Int! title: String! price: Int! } type User { id: Int! email: String! } type OrderItem { id: Int! product: Product! quantity: Int! } type Order { id: Int! orderItems: [OrderItem!]! user: User! } # Some helper types for defining the query types type ProductFilter { id: Int title_like: String price_lt: Int price_gt: Int } type OrderFilter { id: Int userEmail: String userId: Int productTitle: String productId: Int } # Define what can be queried type Query { #Query user user(email: String!): User! #query products products(where: ProductFilter, limit: Int, offset: Int): [Product!]! #query orders orders(where: OrderFilter, limit: Int, offset: Int): [Order] } # Helper types for defining mutations (updates) type OrderItemInput { product: Product! quantity: Int! } type OrderInput{ orderItems: [OrderItemInput!]! user: User! } scalar Void # Define possible updates type Mutation { insertOrder(input: OrderInput!): Order! updateOrderItem(id: Int!, quantity: Int!): OrderItem! cancelOrder(id: Int): Void }
  1. To really achieve #1 and #2, resolvers will usually need to take various filter, pagination, and sort options.
  2. Optimizing resolvers is tricky because different clients will request for different subsets of the data.
  3. You need to worry about avoiding N+1 queries while implementing resolvers.
  4. It is easy for the client to construct complex nested (and potentially recursive) queries that make the server to a lot of work. This can lead to DoS for other clients.

GraphQL vs REST

How does GraphQL break the REST architectural style?

When should I use GraphQL?

Can’t I just use query parameters to specify the exact data I need without breaking REST?

  1. Any sort of query language will need parsing and implementation on the backend. GraphQL has much better tooling to do this.
  2. With GraphQL, the response shape is the same as the request shape, making it easier for clients to access the response.

Conclusion

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store