REST API Design Rulebook
by Mark Massé
Half a solid checklist for consistent REST APIs, half a pitch for a format nobody adopted.
- Status
- Read · May 2021
- Bought
- May 17, 2021
- For
- Backend & API engineers · Anyone standardizing URI and resource conventions across a team
Where it earned its place
The one-paragraph verdict
The first half is genuinely useful: crisp rules for URI structure, status-code semantics, content negotiation, and versioning, each with a short rationale you can actually quote in a code review. It is short enough to finish in a sitting, which is the point. The problem, and the most common complaint in reviews, is that a large chunk of the book pivots into WRML — the author’s own media-type framework — which never gained traction and now reads as dated advocacy rather than guidance. Take the rules, leave the format. As a rulebook it earns its name; as a design philosophy it overreaches.
Who should read it
Backend engineers settling arguments about plural nouns, trailing slashes, and when a 422 beats a 400 will get value fast. Teams that want a shared, citable convention sheet will too. Anyone looking for deep REST/HATEOAS theory, or a current view of API design in a GraphQL/gRPC world, should look elsewhere.
Where it earned its place
The consistency rules shaped how I structured endpoints in my FastEndpoints API work — predictable resource URIs, honest status codes, and explicit versioning rather than ad-hoc query flags. None of it was novel, but having one terse reference made the conventions easy to enforce.
Skip it if…
You already use HTTP correctly, or you want anything beyond a rules checklist — the WRML chapters have not aged well, and there are fresher treatments of the same ground.