liveBook · Manning

Rest api

As explained in Grokking Software Architecture

A REST API is a web API designed around resources and the constraints of Representational State Transfer.

A REST API is one way to expose a public contract over HTTP. Its predictable endpoints can use standard HTTP semantics and caching, making it a practical choice for public-facing services. section 6.4 section 6.4.3

Weigh the benefits against the cost of multiple requests:

  • For external partners, familiar HTTP semantics can make an API easier to adopt, while HTTP caching can reduce server load. section 6.4.3
  • When a client needs related data from several endpoints, REST may require multiple round-trips; GraphQL can request that data together. section 6.4.3

A public partner API

A grocery-store partner needs to sync chip inventory. The decision is to use a RESTful API at Level 2 maturity, using verbs, because partners can rely on standard HTTP semantics and caching. section 6.4.3

Figure 6.7 REST is far more “chatty”, needing multiple roundtrips, while GraphQL only needs a single roundtrip!

Compare the multiple REST round-trips with GraphQL’s single request for the warehouse scanner. section 6.4.3

How Grokking Software Architecture covers it

How deep it goes
Compare caching and request patterns, then justify a Level 2 REST decision without detailing endpoint implementation.
Examples
Illustrates partner inventory syncing and a warehouse scanner requesting product, stock, and location data.
What it assumes
Assumes an API is a public contract and asks who consumes it before choosing a style.
What you can do after
Evaluate REST against GraphQL for a consumer’s needs and record the choice in an Architecture Decision Record.
How it connects
Connects REST to GraphQL, HTTP caching, and Architecture Decision Records.

Also explained in

Compare how 4 books explain rest api →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Grokking Software Architecture. The section links point to the parts of the book it draws on.