A good Web API is recognized not by a pretty URL, but by how little hidden knowledge it demands from its consumer.
In real design work, the chapter shows how URI design, link relations, URI templates, and shared naming rules reduce consumer cognitive load.
In interviews and engineering discussions, it helps discuss API consistency through client confusion, reuse, and behavioral clarity rather than style preferences.
Practical value of this chapter
Design in practice
Design URIs and link relations so consumers do not need private server-side knowledge.
Decision quality
Make API consistency measurable through style rules and repeatable design decisions.
Interview articulation
Explain how API usability affects integration cost and partner time-to-market.
Failure framing
Reduce consumer confusion caused by inconsistent names and behavior.
Source
Book review
Original review by Alexander Polomodov on tellmeabout.tech
Web API Design: The Missing Link
Authors: Brian Mulloy
Publisher: Apigee (Google Cloud)
Length: ~60 pages
Apigee's practical guide to Web API design: resource links, HTTP semantics, URI templates, HATEOAS, URL design, and API consumption quality.
This chapter treats quality of consumption as the real measure of API design: resource links, URI templates, HTTP semantics, predictable URLs, and client behavior become one design language.
Key principles
Related topic
Continuous API Management
API lifecycle, contract governance, and safe interface evolution
The authors propose designing Web APIs from resources, links, and client behavior:
REST and HTTP semantics
The API is shaped around resources, standard methods, and consistent behavior rather than ad hoc RPC-style actions.
Links instead of bare IDs
The core idea of the book is to return resource links so clients can see where they can navigate next.
HTTP and standards
The design leans on HTTP, RFCs, and stable API contracts instead of private team conventions.
Standard
RFC 6570
URI Template specification for variable-based addresses
URI templates
URI templates from RFC 6570 describe variable-based addresses while keeping URL structure predictable.
A good API becomes simpler not when another convenient endpoint is added, but when unnecessary exceptions, hidden rules, and ambiguous addresses are removed.
API design elements
The book breaks Web API design into decisions that clients experience every day:
Resource representation
Fields, nesting, and links to related resources should remain stable for clients.
HTTP headers
Headers express caching, media types, authorization, and other request-level behavior.
URLs and URI templates
Addresses and URI templates help clients make requests and discover resources without hidden model knowledge.
Client behavior
Clients need DNS caching, retries, and tolerance for new JSON fields as the API evolves.
URL design
Practice
API Gateway
Routing, edge policy, and request processing
In a REST-oriented API, the URL should name the resource returned in the response, not the algorithm used to produce it.
Good
- Nouns in URLs
- Plural names for collections
- Properties in path segments
- Resource relationships in URLs
Risky
- Verbs in URLs
- Function-like names such as convert or translate
- Query parameters instead of path segments
- Unpredictable address structures
Example: two kinds of entity references
Lookup by a unique parameter:
/persons?email=john@example.com
Permanent link by UUID:
/persons/550e8400-e29b-41d4-a716-446655440000
If the email changes, the permanent resource link can remain stable.
Query URL design
The authors separate resource relationships from arbitrary filtering: path segments are better for stable relationships, while query parameters fit search and additional conditions.
✓ Recommended for resource relationships
/persons/{personId}/dogsThe owner-to-pets relationship is visible in the URL.
✗ Risky for the primary relationship
/search?type=Dog&owner={personId}The relationship is hidden inside search parameters.
The practical check is simple: a URL should help the client understand which resource it will receive, not force it to guess the server-side calculation.
Why links matter
Links turn JSON from a set of fields into a navigation model: the client sees not only data, but also the next valid transitions.
Bare identifiers
{
"id": "123",
"name": "Rex",
"ownerId": "456"
}Resource links
{
"id": "123",
"name": "Rex",
"owner": "/persons/456"
}This reduces hidden agreements: API consumers do not need to know every URI template in advance to follow a related resource.
Book contents
The book moves from the basic resource model to versioning, HATEOAS, caching, and practical Web API recommendations.
Main takeaway
HTTP gives teams a strong baseline for CRUD semantics, but it does not decide how data queries, resource relationships, and navigation rules should be expressed. That is why URL and representation design remain real engineering work.
Related chapters
- Continuous API Management (short summary) - The API-as-a-product operating model: lifecycle, contract governance, and safe interface evolution.
- API Design Patterns (short summary) - Contract design patterns and backward-compatibility rules for long-lived API ecosystems.
- Customer-Friendly API: Product approach and design - A client-first view of API design: clarity, predictability, and lower integration friction for developers.
- API Gateway - Applied routing, edge policy, and traffic control for Web API systems.
- Inter-service communication patterns - How API contract quality impacts service-to-service reliability and integration cost over time.
- API Security Patterns - Web API security practices: authentication, authorization, threat models, and policy enforcement.
- Learning GraphQL (short summary) - A REST-vs-GraphQL comparison for client-facing API design and API-layer trade-offs.