RESTful Web APIs by Leonard Richardson, Mike Amundsen -- Read -- Imperial Library of Trantor

Index

RESTful Web APIs Dedication Dedication Foreword Introduction

Duplication of Effort Hypermedia Is Hard What’s in This Book? What’s Not in This Book Administrative Notes Understanding Standards

Fiat Standards Personal Standards Corporate Standards Open Standards

Requests for Comments (RFCs) and Internet-Drafts

Conventions Used in This Book Using Code Examples Safari® Books Online How to Contact Us Acknowledgements

1. Surfing the Web

Episode 1: The Billboard

Resources and Representations Addressability

Episode 2: The Home Page

Short Sessions Self-Descriptive Messages

Episode 3: The Link

Standardized Methods

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

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

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

GET DELETE Idempotence POST-to-Append PUT PATCH LINK and UNLINK HEAD OPTIONS Overloaded POST

Which Methods Should You Use?

4. Hypermedia

HTML as a Hypermedia Format URI Templates URI Versus URL The Link Header What Hypermedia Is For

Guiding the Request Promises About the Response Workflow Control

Beware of Fake Hypermedia! The Semantic Challenge: How Are We Doing?

5. Domain-Specific Designs

Maze+XML: A Domain-Specific Design How Maze+XML Works

Link Relations Follow a Link to Change Application State

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

The Fix (and the Flaw in the Fix)

Maze as Metaphor Meeting the Semantic Challenge Where Are the Domain-Specific Designs?

The Prize at the End Hypermedia in the Headers Steal the Application Semantics

If You Can’t Find a Domain-Specific Design, Don’t Make One Kinds of API Clients

Human-Driven Clients Automated Clients

The crawler The monitor The script The agent

6. The Collection Pattern

What’s a Collection?

Collections Link to Items

Collection+JSON

Representing the Items

An item’s permanent link An item’s data An item’s links

The Write Template Search Templates

How a (Generic) Collection Works

GET POST-to-Append PUT and PATCH DELETE Pagination Search Forms

The Atom Publishing Protocol (AtomPub)

AtomPub Plug-in Standards Why Doesn’t Everyone Use AtomPub?

The Semantic Challenge: How Are We Doing?

7. Pure-Hypermedia Designs

Why HTML? HTML’s Capabilities

Hypermedia Controls Plug-in Application Semantics

The rel attribute The id attribute The class attribute

Microformats The hMaze Microformat Microdata Changing Resource State

Adding Application Semantics to Forms

The Alternative to Hypermedia Is Media HTML’s Limits

HTML 5 to the Rescue?

The Hypertext Application Language Siren The Semantic Challenge: How Are We Doing?

8. Profiles

How Does A Client Find the Documentation? What’s a Profile? Linking to a Profile

The profile Link Relation The profile Media Type Parameter Special-Purpose Hypermedia Controls

Profiles Describe Protocol Semantics Profiles Describe Application Semantics

Link Relations Unsafe Link Relations Semantic Descriptors

XMDP: The First Machine-Readable Profile Format ALPS

Advantages of ALPS ALPS Doesn’t Do Everything

JSON-LD Embedded Documentation In Summary

9. The Design Procedure

Two-Step Design Procedure Seven-Step Design Procedure

Step 1: List the Semantic Descriptors Step 2: Draw a State Diagram

Semantic descriptors may become link relations Locating the home page

Step 3: Reconcile Names Step 4: Choose a Media Type Step 5: Write a Profile Step 6: Implementation Step 7: Publication

Publish your billboard URL Publish your profile Register new media types Register new link relations Publish the rest of the documentation Well-known URIs

Example: You Type It, We Post It

List the Semantic Descriptors Draw a State Diagram Reconcile Names Choose a Media Type Write a Profile

Some Design Advice

Resources Are Implementation Details Don’t Fall into the Collection Trap Don’t Start with the Representation Format URL Design Doesn’t Matter Standard Names Are Probably Better Than Your Names If You Design a Media Type When Your API Changes

Partitioning the URL space Versioning the media type Versioning the profile Versoning isn’t special Have an end-of-life plan

Don’t Keep All the Hypermedia in One Place

Adding Hypermedia to an Existing API

Fixing Up an XML-Based API Is It Worth It?

Alice’s Second Adventure

Episode 1: The Nonsense Representation Episode 2: The Profile Alice Figured It Out

10. The Hypermedia Zoo

Domain-Specific Formats

Maze+XML OpenSearch Problem Detail Documents SVG VoiceXML

Collection Pattern Formats

Collection+JSON The Atom Publishing Protocol OData

Filtering Functions and the metadata document Metadata documents as service description documents

Pure Hypermedia Formats

HTML HAL Siren The Link Header The Location and Content-Location Headers URL Lists JSON Home Documents The Link-Template Header WADL XLink XForms

GeoJSON: A Troubled Type

GeoJSON Has No Generic Hypermedia Controls GeoJSON Has No Media Type Learning from GeoJSON

The Semantic Zoo

The IANA Registry of Link Relations The Microformats Wiki Link Relations from the Microformats Wiki schema.org Dublin Core Activity Streams The ALPS Registry

11. HTTP for APIs

The New HTTP/1.1 Specification Response Codes Headers Choosing Between Representations

Content Negotiation

Negotiating a profile

Hypermedia Menus The Canonical URL

HTTP Performance

Caching Conditional GET Look-Before-You-Leap Requests Compression Partial GET Pipelining

Avoiding the Lost Update Problem Authentication

The WWW-Authenticate and Authorization Headers Basic Auth OAuth 1.0 Where OAuth 1.0 Falls Short OAuth 2.0 When to Give Up on OAuth

Extensions to HTTP

The PATCH Method The LINK and UNLINK Methods WebDAV

HTTP 2.0

12. Resource Description and Linked Data

RDF

RDF Treats URLs as URIs

When to Use the Description Strategy Resource Types RDF Schema The Linked Data Movement JSON-LD

JSON-LD as a Representation Format

Hydra The XRD Family

XRD and JRD Web Host Metadata Documents WebFinger

The Ontology Zoo

schema.org RDF FOAF vocab.org

Conclusion: The Description Strategy Lives!

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

A. The Status Codex

Problem Detail Documents Families of Status Codes Four Status Codes: The Bare Minimum 1xx: Informational

100 (Continue) 101 (Switching Protocols)

2xx: Successful

200 (OK) 201 (Created) 202 (Accepted) 203 (Non-Authoritative Information) 204 (No Content) 205 (Reset Content) 206 (Partial Content)

3xx: Redirection

300 (Multiple Choices) 301 (Moved Permanently) 302 (Found) 303 (See Other) 304 (Not Modified) 305 (Use Proxy) 306: Unused 307 (Temporary Redirect) 308 (Permanent Redirect)

4xx: Client-Side Error

400 (Bad Request) 401 (Unauthorized) 402 (Payment Required) 403 (Forbidden) 404 (Not Found) 405 (Method Not Allowed) 406 (Not Acceptable) 407 (Proxy Authentication Required) 408 (Request Timeout) 409 (Conflict) 410 (Gone) 411 (Length Required) 412 (Precondition Failed) 413 (Request Entity Too Large) 414 (Request-URL Too Long) 415 (Unsupported Media Type) 416 (Requested Range Not Satisfiable) 417 (Expectation Failed) 428 (Precondition Required) 429 (Too Many Requests) 431 (Request Header Fields Too Large) 451 (Unavailable For Legal Reasons)

5xx: Server-Side Error

500 (Internal Server Error) 501 (Not Implemented) 502 (Bad Gateway) 503 (Service Unavailable) 504 (Gateway Timeout) 505 (HTTP Version Not Supported) 511 (Network Authentication Required)

B. The Header Codex

Custom HTTP Headers The Headers

Accept Accept-Charset Accept-Encoding Accept-Language Accept-Ranges Age Allow Authorization Cache-Control Connection Content-Disposition Content-Encoding Content-Language Content-Length Content-Location Content-MD5 Content-Range Content-Type Cookie Date ETag Expect Expires From Host If-Match If-Modified-Since If-None-Match If-Range If-Unmodified-Since Last-Modified Link Link-Template Location Max-Forwards Pragma Prefer Preference-Applied Proxy-Authenticate Proxy-Authorization Range Referer Retry-After Set-Cookie Slug TE Trailer Transfer-Encoding Upgrade User-Agent Vary Via Warning WWW-Authenticate

C. An API Designer’s Guide to the Fielding Dissertation

Architectural Properties of the Web

Low Entry-Barrier Extensibility Distributed Hypermedia Internet-Scale APIs Are Not (Quite) the Web

Interface Constraints

Identification of Resources Manipulation of Resources Through Representations Self-Descriptive Messages The Hypermedia Constraint

Architectural Constraints

Client-Server Statelessness Caching Uniform Interface Layered System Code on Demand

Summary Conclusion

Glossary Index About the Authors Colophon Copyright

← Prev
Back
Next →

← Prev
Back
Next →