Facebook Pixel
Searching...
English
EnglishEnglish
EspañolSpanish
简体中文Chinese
FrançaisFrench
DeutschGerman
日本語Japanese
PortuguêsPortuguese
ItalianoItalian
한국어Korean
РусскийRussian
NederlandsDutch
العربيةArabic
PolskiPolish
हिन्दीHindi
Tiếng ViệtVietnamese
SvenskaSwedish
ΕλληνικάGreek
TürkçeTurkish
ไทยThai
ČeštinaCzech
RomânăRomanian
MagyarHungarian
УкраїнськаUkrainian
Bahasa IndonesiaIndonesian
DanskDanish
SuomiFinnish
БългарскиBulgarian
עבריתHebrew
NorskNorwegian
HrvatskiCroatian
CatalàCatalan
SlovenčinaSlovak
LietuviųLithuanian
SlovenščinaSlovenian
СрпскиSerbian
EestiEstonian
LatviešuLatvian
فارسیPersian
മലയാളംMalayalam
தமிழ்Tamil
اردوUrdu
REST API Design Rulebook

REST API Design Rulebook

by Mark Masse 2011 112 pages
3.34
100+ ratings
Listen

Key Takeaways

1. REST APIs leverage HTTP's full capabilities for scalable web communication

REST tells us how the Web achieves its great scale.

Architectural constraints enable scalability. REST (Representational State Transfer) is the architectural style of the World Wide Web, designed to enable massive scalability. It achieves this through key constraints:

  • Client-server separation of concerns
  • Stateless interactions
  • Uniform interface (including resource identification, manipulation through representations, self-descriptive messages, and hypermedia controls)
  • Layered system allowing intermediaries
  • Caching to reduce latency
  • Optional code-on-demand for client extensibility

These constraints work together to create a distributed system capable of handling enormous numbers of interactions while remaining flexible and performant.

2. URIs should uniquely identify resources without revealing implementation details

Every character within a URI counts toward a resource's unique identity.

Design clear, hierarchical URIs. URIs (Uniform Resource Identifiers) are the cornerstone of REST APIs, uniquely identifying each resource. Best practices for URI design include:

  • Use forward slashes to indicate hierarchical relationships
  • Prefer lowercase letters
  • Use hyphens to improve readability
  • Avoid file extensions
  • Use plural nouns for collections
  • Use singular nouns for specific resources
  • Employ consistent naming conventions across the API

Well-designed URIs should be intuitive and self-describing, allowing developers to understand the resource structure without needing extensive documentation. However, clients should treat URIs as opaque identifiers and not attempt to parse meaning from them directly.

3. HTTP methods define standard interactions with resources

A REST API must not compromise its design by misusing HTTP's request methods in an effort to accommodate clients with limited HTTP vocabulary.

Use HTTP methods consistently. The standard HTTP methods provide a uniform interface for interacting with resources:

  • GET: Retrieve a resource representation
  • POST: Create a new resource in a collection or execute a controller
  • PUT: Update an existing resource or create a new resource in a store
  • DELETE: Remove a resource
  • HEAD: Retrieve metadata about a resource
  • OPTIONS: Discover available interactions for a resource

Each method has specific semantics and expected behavior. For example, GET should be safe and idempotent, while POST may have side effects. Consistently applying these methods across your API design enhances predictability and interoperability.

4. Metadata in HTTP headers enhances API functionality and performance

Caching is one of the most useful features built on top of HTTP.

Leverage HTTP headers for metadata. HTTP headers provide a wealth of functionality for REST APIs:

  • Content-Type: Specifies the media type of the request or response body
  • ETag: Enables efficient caching and conditional requests
  • Cache-Control: Directs caching behavior for improved performance
  • Authorization: Supports various authentication schemes
  • Accept: Allows content negotiation for different representations

Proper use of headers can significantly improve API performance, security, and flexibility. For example, effective use of caching headers can reduce server load and improve response times, while authentication headers enable secure access control.

5. Resource representations should use consistent formats and hypermedia controls

REST API clients should be encouraged to rely on the self-descriptive features of a REST API.

Design self-describing representations. Resource representations should be consistent and self-describing:

  • Use standard formats like JSON or XML
  • Include hypermedia controls (links) to guide clients through available actions
  • Employ consistent structures for common elements like errors
  • Use descriptive field names and appropriate data types
  • Include metadata about the representation (e.g., schema information)

Hypermedia controls are particularly important, as they allow the API to guide clients through the application state. This enables looser coupling between clients and servers, improving the API's evolvability.

6. Versioning, security, and composition strategies improve API flexibility

OAuth is an HTTP-based authorization protocol that enables the protection of resources.

Design for evolution and security. Key strategies for flexible and secure APIs include:

  • Versioning: Use schema versioning rather than URI versioning
  • Security: Implement OAuth or API management solutions for access control
  • Partial responses: Allow clients to request only needed fields
  • Embedded resources: Enable clients to retrieve related resources in a single request
  • Error handling: Provide consistent, informative error responses

These strategies allow APIs to evolve over time without breaking existing clients, while also providing the security and efficiency features required by modern applications.

7. JavaScript clients require special considerations for cross-origin requests

CORS is an alternative to JSONP that supports all request methods.

Enable cross-origin access. Browser security restrictions can pose challenges for JavaScript clients accessing APIs from different domains. Two main approaches address this:

  • JSONP (JSON with Padding): Allows read-only access by exploiting script tag behavior
  • CORS (Cross-Origin Resource Sharing): Provides full read/write access with browser support

CORS is the more robust and standardized approach, supporting all HTTP methods. By implementing CORS, APIs can securely allow access from JavaScript applications hosted on different domains, enabling rich web applications and mashups.

Last updated:

Review Summary

3.34 out of 5
Average of 100+ ratings from Goodreads and Amazon.

REST API Design Rulebook receives mixed reviews. Many readers find the first half valuable for REST API design principles, but criticize the second half's focus on WRML, the author's proposed framework. Positive aspects include clear rules for API design, especially in early chapters. Criticisms include the book's brevity, repetitiveness, and overemphasis on WRML. Some readers suggest using it as a reference rather than reading cover-to-cover. Overall, the book is seen as a good introduction to REST API design, but potentially outdated and overly opinionated in parts.

Your rating:

About the Author

Mark Masse is a software engineer and author known for his work on REST API design. He wrote "REST API Design Rulebook" to provide guidance on creating effective and standardized REST APIs. Masse developed WRML (Web Resource Modeling Language), a proposed framework for designing hypermedia-driven APIs, which features prominently in his book. His expertise lies in web architecture, API design, and software engineering principles. While some readers appreciate his thorough approach to API design rules, others find his emphasis on WRML controversial and potentially impractical. Masse's work aims to bridge the gap between theoretical REST principles and practical implementation in modern web development.

Download PDF

To save this REST API Design Rulebook summary for later, download the free PDF. You can print it out, or read offline at your convenience.
Download PDF
File size: 0.30 MB     Pages: 8

Download EPUB

To read this REST API Design Rulebook summary on your e-reader device or app, download the free EPUB. The .epub digital book format is ideal for reading ebooks on phones, tablets, and e-readers.
Download EPUB
File size: 3.04 MB     Pages: 6
0:00
-0:00
1x
Dan
Andrew
Michelle
Lauren
Select Speed
1.0×
+
200 words per minute
Create a free account to unlock:
Bookmarks – save your favorite books
History – revisit books later
Ratings – rate books & see your ratings
Unlock unlimited listening
Your first week's on us!
Today: Get Instant Access
Listen to full summaries of 73,530 books. That's 12,000+ hours of audio!
Day 4: Trial Reminder
We'll send you a notification that your trial is ending soon.
Day 7: Your subscription begins
You'll be charged on Nov 21,
cancel anytime before.
Compare Features Free Pro
Read full text summaries
Summaries are free to read for everyone
Listen to summaries
12,000+ hours of audio
Unlimited Bookmarks
Free users are limited to 10
Unlimited History
Free users are limited to 10
What our users say
30,000+ readers
“...I can 10x the number of books I can read...”
“...exceptionally accurate, engaging, and beautifully presented...”
“...better than any amazon review when I'm making a book-buying decision...”
Save 62%
Yearly
$119.88 $44.99/yr
$3.75/mo
Monthly
$9.99/mo
Try Free & Unlock
7 days free, then $44.99/year. Cancel anytime.
Settings
Appearance