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 and make an interface more predictable.
In interviews and engineering discussions, it helps talk about API consistency through consumer confusion, reuse, and semantic clarity rather than through style preferences.
Practical value of this chapter
Design in practice
Design URI and link relations so consumers can use APIs without hidden tribal knowledge.
Decision quality
Make API consistency measurable through style rules and reusable patterns.
Interview articulation
Explain how API UX affects integration cost and partner time-to-market.
Failure framing
Reduce consumer confusion caused by inconsistent naming and semantics.
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
A practical guide from Apigee: RESTful design, links instead of IDs, URI Templates, URL design and HATEOAS.
Key principles
Related topic
Continuous API Management
Deep dive into the Lifecycle and Governance APIs
The authors propose a data-centric approach to API design:
RESTful style
Using the REST architectural style with an emphasis on simplicity and ease of understanding.
Links instead of ID
The emphasis on using links to resources instead of just identifiers is the main idea of the book.
HTTP + RFC
REST paired with HTTP, active use of recommendations from RFC standards.
Standard
RFC 6570
URI Template - specification for expressing URIs through variables
URI Templates
Using URI templates concepts from RFC 6570 for predictable URLs.
“Perfection is achieved not when nothing can be added, but when nothing can be taken away.”
— Antoine de Saint-Exupéry
API Design Elements
The authors highlight the key elements that make up the API design:
Resource View
Defining the fields and format of links to related resources
HTTP headers
Using standard and custom headers
URL and URI Templates
Interface for making queries and finding resources
Customer Behavior
DNS caching, retries, resistance to new fields in JSON
URL Design
Practice
API Gateway
Routing and request processing patterns
URL Design Guidelines for RESTful APIs:
Fine
- Nouns in URL
- Plural for collections
- Properties in the route path
- Relationships in URLs
Badly
- Verbs in URL
- Functions like convert/translate
- Query parameters instead of path
- Unpredictable structures
Example: two types of entity references
Query by unique parameter:
/persons?email=john@example.com
Permanent permalink by UUID:
/persons/550e8400-e29b-41d4-a716-446655440000
* This allows you not to change permalink when changing email
Query URL Design
The authors recommend placing filtering properties in the path rather than in GET parameters:
✓ Recommended
/persons/{personId}/dogsRelationships are expressed in URLs
✗ Not recommended
/search?type=Dog&owner={personId}Hidden Relationships
"The key insight is that the URL should identify the resource in the response, not the processing algorithm that calculates the response"
Why links are important
The main idea of the book is to use resource links instead of simple identifiers:
Instead of ID
{
"id": "123",
"name": "Rex",
"ownerId": "456"
}Links to resources
{
"id": "123",
"name": "Rex",
"owner": "/persons/456"
}Links make the API self-documenting and make it easy to navigate to related resources, even if the client doesn't know the templates URI.
Contents of the book
The book contains 12 sections that cover all aspects of Web API design:
Main conclusion
"HTTP provides a standard API for the basic CRUD portion of every web API, but it does not have as much to say about how queries over the data are expressed. This is why a significant amount of design effort typically goes into the design of URLs that express queries"
HTTP provides a standard interface for CRUD operations, but query URL design requires significant design effort.
Related chapters
- Continuous API Management (short summary) - An API-as-a-Product operating model: lifecycle governance and controlled API contract 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 - Developer-experience-driven API design for clarity, predictability, and lower integration friction.
- API Gateway - Applied routing, edge-policy execution, and traffic control in production 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 layer-level trade-off decisions.