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.
A pretty address is worth nothing if the client struggles to work with it. So the book puts quality of consumption first and folds into one design language what teams usually decide separately: resource links, URI templates, HTTP semantics, predictable URLs, and the real behavior of the API consumer.
Key principles
Related topic
Continuous API Management
API lifecycle, contract governance, and safe interface evolution
The starting point is not a list of endpoints but resources, the relationships between them, and client behavior. Four supports grow out of that:
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
Web API design splits into a few decisions that clients experience every day. Get any of them wrong, and the friction lands not on the team but on whoever writes the integration:
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: add a field and an older client must not break.
URL design
Practice
API Gateway
Routing, edge policy, and request processing
In a REST-oriented API, the URL names the resource returned in the response, not the algorithm used to produce it. The moment a verb or a function name creeps into the address, the client starts encoding the server's internal logic — and any change to that logic breaks the integration.
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 check is simple: from the URL the client should understand which resource it will receive, not guess the server-side calculation. If answering that question needs documentation, the address has already lost.
Why links matter
A bare identifier tells the client a relationship exists but says nothing about how to follow it. A link turns JSON from a set of fields into a navigation model: the next valid transitions sit right next to the data.
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 chapters move from the basic resource model toward the topics where mistakes cost the most: versioning, hypermedia navigation (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 — the protocol hands you an alphabet, and you write the interface's language yourself.
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.