RESTful Web APIs

Leonard Richardson is the author of the Ruby Cookbook (O'Reilly) and of several open source libraries, including »Beautiful Soup«. A California native, he currently lives in New York.

An internationally known author and lecturer, Mike Amundsen travels throughout the United States and Europe consulting and speaking on a wide range of topics including distributed network architecture, Web application development, Cloud computing, and other subjects. His recent work focuses on the role hypermedia plays in creating and maintaining applications that can successfully evolve over time. He has more than a dozen books to his credit and recently contributed to the book "RESTful Web Services Cookbook" (by Subbu Allamaraju). When he is not working, Mike enjoys spending time with his family in Kentucky, USA.

Sam Ruby is a prominent software developer who is a co-chair of the W3C HTML Working Group and has made significant contributions to many of the Apache Software Foundation's open source software projects. He is a Senior Technical Staff Member in the Emerging Technologies Group of IBM.

Chapter 1 Surfing the Web
Episode 1: The Billboard
Episode 2: The Home Page
Episode 3: The Link
Episode 4: The Form and the Redirect
Application State
Resource State
Connectedness
The Web Is Something Special
Web APIs Lag Behind the Web
The Semantic Challenge
Chapter 2 A Simple API
HTTP GET: Your Safe Bet
How to Read an HTTP Response
JSON
Collection+JSON
Writing to an API
HTTP POST: How Resources Are Born
Liberated by Constraints
Application Semantics Create the Semantic Gap
Chapter 3 Resources and Representations
A Resource Can Be Anything
A Representation Describes Resource State
Representations Are Transferred Back and Forth
Resources with Many Representations
The Protocol Semantics of HTTP
Which Methods Should You Use?
Chapter 4 Hypermedia
HTML as a Hypermedia Format
URI Templates
URI Versus URL
The Link Header
What Hypermedia Is For
Beware of Fake Hypermedia!
The Semantic Challenge: How Are We Doing?
Chapter 5 Domain-Specific Designs
Maze+XML: A Domain-Specific Design
How Maze+XML Works
The Collection of Mazes
Is Maze+XML an API?
Client #1: The Game
A Maze+XML Server
Client #2: The Mapmaker
Client #3: The Boaster
Clients Do the Job They Want to Do
Extending a Standard
The Mapmaker’s Flaw
Maze as Metaphor
Meeting the Semantic Challenge
Where Are the Domain-Specific Designs?
If You Can’t Find a Domain-Specific Design, Don’t Make One
Kinds of API Clients
Chapter 6 The Collection Pattern
What’s a Collection?
Collection+JSON
How a (Generic) Collection Works
The Atom Publishing Protocol (AtomPub)
The Semantic Challenge: How Are We Doing?
Chapter 7 Pure-Hypermedia Designs
Why HTML?
HTML’s Capabilities
Microformats
The hMaze Microformat
Microdata
Changing Resource State
The Alternative to Hypermedia Is Media
HTML’s Limits
The Hypertext Application Language
Siren
The Semantic Challenge: How Are We Doing?
Chapter 8 Profiles
How Does A Client Find the Documentation?
What’s a Profile?
Linking to a Profile
Profiles Describe Protocol Semantics
Profiles Describe Application Semantics
XMDP: The First Machine-Readable Profile Format
ALPS
JSON-LD
Embedded Documentation
In Summary
Chapter 9 The Design Procedure
Two-Step Design Procedure
Seven-Step Design Procedure
Example: You Type It, We Post It
Some Design Advice
Adding Hypermedia to an Existing API
Alice’s Second Adventure
Chapter 10 The Hypermedia Zoo
Domain-Specific Formats
Collection Pattern Formats
Pure Hypermedia Formats
GeoJSON: A Troubled Type
The Semantic Zoo
Chapter 11 HTTP for APIs
The New HTTP/1.1 Specification
Response Codes
Headers
Choosing Between Representations
HTTP Performance
Avoiding the Lost Update Problem
Authentication
Extensions to HTTP
HTTP 2.0
Chapter 12 Resource Description and Linked Data
RDF
When to Use the Description Strategy
Resource Types
RDF Schema
The Linked Data Movement
JSON-LD
Hydra
The XRD Family
The Ontology Zoo
Conclusion: The Description Strategy Lives!
Chapter 13 CoAP: REST for Embedded Systems
A CoAP Request
A CoAP Response
Kinds of Messages
Delayed Response
Multicast Messages
The CoRE Link Format
Conclusion: REST Without HTTP

Appendix The Status Codex
Problem Detail Documents
Families of Status Codes
Four Status Codes: The Bare Minimum
1xx: Informational
2xx: Successful
3xx: Redirection
4xx: Client-Side Error
5xx: Server-Side Error
Appendix The Header Codex
Custom HTTP Headers
The Headers
Appendix An API Designer’s Guide to the Fielding Dissertation
Architectural Properties of the Web
Interface Constraints
Architectural Constraints
Summary
Conclusion
Glossary
Index
Colophon