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.
OriginalKey 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.