RESTful Web APIs

RESTful Web APIs

by Leonard Richardson, Mike Amundsen, Sam Ruby
Released September 2013
Publisher(s): O'Reilly Media, Inc.
ISBN: 9781449359737

Read it now on the O’Reilly learning platform with a 10-day free trial.

O’Reilly members get unlimited access to books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial

Book description

The popularity of REST in recent years has led to tremendous growth in almost-RESTful APIs that don’t include many of the architecture’s benefits. With this practical guide, you’ll learn what it takes to design usable REST APIs that evolve over time. By focusing on solutions that cross a variety of domains, this book shows you how to create powerful and secure applications, using the tools designed for the world’s most successful distributed computing system: the World Wide Web.

You’ll explore the concepts behind REST, learn different strategies for creating hypermedia-based APIs, and then put everything together with a step-by-step guide to designing a RESTful Web API.

  • Examine API design strategies, including the collection pattern and pure hypermedia
  • Understand how hypermedia ties representations together into a coherent API
  • Discover how XMDP and ALPS profile formats can help you meet the Web API "semantic challenge"
  • Learn close to two-dozen standardized hypermedia data formats
  • Apply best practices for using HTTP in API implementations
  • Create Web APIs with the JSON-LD standard and other the Linked Data approaches
  • Understand the CoAP protocol for using REST in embedded systems

Table of contents

  1. Praise for RESTful Web APIs
  2. Dedication
  3. Foreword
  4. Introduction
    1. Duplication of Effort
    2. Hypermedia Is Hard
    3. What’s in This Book?
    4. What’s Not in This Book
    5. Administrative Notes
    6. Understanding Standards
      1. Fiat Standards
      2. Personal Standards
      3. Corporate Standards
      4. Open Standards
        1. Requests for Comments (RFCs) and Internet-Drafts
    7. Conventions Used in This Book
    8. Using Code Examples
    9. Safari® Books Online
    10. How to Contact Us
    11. Acknowledgments
  5. 1. Surfing the Web
    1. Episode 1: The Billboard
      1. Resources and Representations
      2. Addressability
    2. Episode 2: The Home Page
      1. Short Sessions
      2. Self-Descriptive Messages
    3. Episode 3: The Link
      1. Standardized Methods
    4. Episode 4: The Form and the Redirect
    5. Application State
    6. Resource State
    7. Connectedness
    8. The Web Is Something Special
    9. Web APIs Lag Behind the Web
    10. The Semantic Challenge
  6. 2. A Simple API
    1. HTTP GET: Your Safe Bet
    2. How to Read an HTTP Response
    3. JSON
    4. Collection+JSON
    5. Writing to an API
    6. HTTP POST: How Resources Are Born
    7. Liberated by Constraints
    8. Application Semantics Create the Semantic Gap
  7. 3. Resources and Representations
    1. A Resource Can Be Anything
    2. A Representation Describes Resource State
    3. Representations Are Transferred Back and Forth
    4. Resources with Many Representations
    5. The Protocol Semantics of HTTP
      1. GET
      2. DELETE
      3. Idempotence
      4. POST-to-Append
      5. PUT
      6. PATCH
      7. LINK and UNLINK
      8. HEAD
      9. OPTIONS
      10. Overloaded POST
    6. Which Methods Should You Use?
  8. 4. Hypermedia
    1. HTML as a Hypermedia Format
    2. URI Templates
    3. URI Versus URL
    4. The Link Header
    5. What Hypermedia Is For
      1. Guiding the Request
      2. Promises About the Response
      3. Workflow Control
    6. Beware of Fake Hypermedia!
    7. The Semantic Challenge: How Are We Doing?
  9. 5. Domain-Specific Designs
    1. Maze+XML: A Domain-Specific Design
    2. How Maze+XML Works
      1. Link Relations
      2. Follow a Link to Change Application State
    3. The Collection of Mazes
    4. Is Maze+XML an API?
    5. Client #1: The Game
    6. A Maze+XML Server
    7. Client #2: The Mapmaker
    8. Client #3: The Boaster
    9. Clients Do the Job They Want to Do
    10. Extending a Standard
    11. The Mapmaker’s Flaw
      1. The Fix (and the Flaw in the Fix)
    12. Maze as Metaphor
    13. Meeting the Semantic Challenge
    14. Where Are the Domain-Specific Designs?
      1. The Prize at the End
      2. Hypermedia in the Headers
      3. Steal the Application Semantics
    15. If You Can’t Find a Domain-Specific Design, Don’t Make One
    16. Kinds of API Clients
      1. Human-Driven Clients
      2. Automated Clients
        1. The crawler
        2. The monitor
        3. The script
        4. The agent
  10. 6. The Collection Pattern
    1. What’s a Collection?
      1. Collections Link to Items
    2. Collection+JSON
      1. Representing the Items
        1. An item’s permanent link
        2. An item’s data
        3. An item’s links
      2. The Write Template
      3. Search Templates
    3. How a (Generic) Collection Works
      1. GET
      2. POST-to-Append
      3. PUT and PATCH
      4. DELETE
      5. Pagination
      6. Search Forms
    4. The Atom Publishing Protocol (AtomPub)
      1. AtomPub Plug-in Standards
      2. Why Doesn’t Everyone Use AtomPub?
    5. The Semantic Challenge: How Are We Doing?
  11. 7. Pure-Hypermedia Designs
    1. Why HTML?
    2. HTML’s Capabilities
      1. Hypermedia Controls
      2. Plug-in Application Semantics
        1. The rel attribute
        2. The id attribute
        3. The class attribute
    3. Microformats
    4. The hMaze Microformat
    5. Microdata
    6. Changing Resource State
      1. Adding Application Semantics to Forms
    7. The Alternative to Hypermedia Is Media
    8. HTML’s Limits
      1. HTML 5 to the Rescue?
    9. The Hypertext Application Language
    10. Siren
    11. The Semantic Challenge: How Are We Doing?
  12. 8. Profiles
    1. How Does A Client Find the Documentation?
    2. What’s a Profile?
    3. Linking to a Profile
      1. The profile Link Relation
      2. The profile Media Type Parameter
      3. Special-Purpose Hypermedia Controls
    4. Profiles Describe Protocol Semantics
    5. Profiles Describe Application Semantics
      1. Link Relations
      2. Unsafe Link Relations
      3. Semantic Descriptors
    6. XMDP: The First Machine-Readable Profile Format
    7. ALPS
      1. Advantages of ALPS
      2. ALPS Doesn’t Do Everything
    8. JSON-LD
    9. Embedded Documentation
    10. In Summary
  13. 9. The Design Procedure
    1. Two-Step Design Procedure
    2. Seven-Step Design Procedure
      1. Step 1: List the Semantic Descriptors
      2. Step 2: Draw a State Diagram
        1. Semantic descriptors may become link relations
        2. Locating the home page
      3. Step 3: Reconcile Names
      4. Step 4: Choose a Media Type
      5. Step 5: Write a Profile
      6. Step 6: Implementation
      7. Step 7: Publication
        1. Publish your billboard URL
        2. Publish your profile
        3. Register new media types
        4. Register new link relations
        5. Publish the rest of the documentation
        6. Well-known URIs
    3. Example: You Type It, We Post It
      1. List the Semantic Descriptors
      2. Draw a State Diagram
      3. Reconcile Names
      4. Choose a Media Type
      5. Write a Profile
    4. Some Design Advice
      1. Resources Are Implementation Details
      2. Don’t Fall into the Collection Trap
      3. Don’t Start with the Representation Format
      4. URL Design Doesn’t Matter
      5. Standard Names Are Probably Better Than Your Names
      6. If You Design a Media Type
      7. When Your API Changes
        1. Partitioning the URL space
        2. Versioning the media type
        3. Versioning the profile
        4. Versoning isn’t special
        5. Have an end-of-life plan
      8. Don’t Keep All the Hypermedia in One Place
    5. Adding Hypermedia to an Existing API
      1. Fixing Up an XML-Based API
      2. Is It Worth It?
    6. Alice’s Second Adventure
      1. Episode 1: The Nonsense Representation
      2. Episode 2: The Profile
      3. Alice Figured It Out
  14. 10. The Hypermedia Zoo
    1. Domain-Specific Formats
      1. Maze+XML
      2. OpenSearch
      3. Problem Detail Documents
      4. SVG
      5. VoiceXML
    2. Collection Pattern Formats
      1. Collection+JSON
      2. The Atom Publishing Protocol
      3. OData
        1. Filtering
        2. Functions and the metadata document
        3. Metadata documents as service description documents
    3. Pure Hypermedia Formats
      1. HTML
      2. HAL
      3. Siren
      4. The Link Header
      5. The Location and Content-Location Headers
      6. URL Lists
      7. JSON Home Documents
      8. The Link-Template Header
      9. WADL
      10. XLink
      11. XForms
    4. GeoJSON: A Troubled Type
      1. GeoJSON Has No Generic Hypermedia Controls
      2. GeoJSON Has No Media Type
      3. Learning from GeoJSON
    5. The Semantic Zoo
      1. The IANA Registry of Link Relations
      2. The Microformats Wiki
      3. Link Relations from the Microformats Wiki
      4. schema.org
      5. Dublin Core
      6. Activity Streams
      7. The ALPS Registry
  15. 11. HTTP for APIs
    1. The New HTTP/1.1 Specification
    2. Response Codes
    3. Headers
    4. Choosing Between Representations
      1. Content Negotiation
        1. Negotiating a profile
      2. Hypermedia Menus
      3. The Canonical URL
    5. HTTP Performance
      1. Caching
      2. Conditional GET
      3. Look-Before-You-Leap Requests
      4. Compression
      5. Partial GET
      6. Pipelining
    6. Avoiding the Lost Update Problem
    7. Authentication
      1. The WWW-Authenticate and Authorization Headers
      2. Basic Auth
      3. OAuth 1.0
      4. Where OAuth 1.0 Falls Short
      5. OAuth 2.0
      6. When to Give Up on OAuth
    8. Extensions to HTTP
      1. The PATCH Method
      2. The LINK and UNLINK Methods
      3. WebDAV
    9. HTTP 2.0
  16. 12. Resource Description and Linked Data
    1. RDF
      1. RDF Treats URLs as URIs
    2. When to Use the Description Strategy
    3. Resource Types
    4. RDF Schema
    5. The Linked Data Movement
    6. JSON-LD
      1. JSON-LD as a Representation Format
    7. Hydra
    8. The XRD Family
      1. XRD and JRD
      2. Web Host Metadata Documents
      3. WebFinger
    9. The Ontology Zoo
      1. schema.org RDF
      2. FOAF
      3. vocab.org
    10. Conclusion: The Description Strategy Lives!
  17. 13. CoAP: REST for Embedded Systems
    1. A CoAP Request
    2. A CoAP Response
    3. Kinds of Messages
    4. Delayed Response
    5. Multicast Messages
    6. The CoRE Link Format
    7. Conclusion: REST Without HTTP
  18. A. The Status Codex
    1. Problem Detail Documents
    2. Families of Status Codes
    3. Four Status Codes: The Bare Minimum
    4. 1xx: Informational
      1. 100 (Continue)
      2. 101 (Switching Protocols)
    5. 2xx: Successful
      1. 200 (OK)
      2. 201 (Created)
      3. 202 (Accepted)
      4. 203 (Non-Authoritative Information)
      5. 204 (No Content)
      6. 205 (Reset Content)
      7. 206 (Partial Content)
    6. 3xx: Redirection
      1. 300 (Multiple Choices)
      2. 301 (Moved Permanently)
      3. 302 (Found)
      4. 303 (See Other)
      5. 304 (Not Modified)
      6. 305 (Use Proxy)
      7. 306: Unused
      8. 307 (Temporary Redirect)
      9. 308 (Permanent Redirect)
    7. 4xx: Client-Side Error
      1. 400 (Bad Request)
      2. 401 (Unauthorized)
      3. 402 (Payment Required)
      4. 403 (Forbidden)
      5. 404 (Not Found)
      6. 405 (Method Not Allowed)
      7. 406 (Not Acceptable)
      8. 407 (Proxy Authentication Required)
      9. 408 (Request Timeout)
      10. 409 (Conflict)
      11. 410 (Gone)
      12. 411 (Length Required)
      13. 412 (Precondition Failed)
      14. 413 (Request Entity Too Large)
      15. 414 (Request-URL Too Long)
      16. 415 (Unsupported Media Type)
      17. 416 (Requested Range Not Satisfiable)
      18. 417 (Expectation Failed)
      19. 428 (Precondition Required)
      20. 429 (Too Many Requests)
      21. 431 (Request Header Fields Too Large)
      22. 451 (Unavailable For Legal Reasons)
    8. 5xx: Server-Side Error
      1. 500 (Internal Server Error)
      2. 501 (Not Implemented)
      3. 502 (Bad Gateway)
      4. 503 (Service Unavailable)
      5. 504 (Gateway Timeout)
      6. 505 (HTTP Version Not Supported)
      7. 511 (Network Authentication Required)
  19. B. The Header Codex
    1. Custom HTTP Headers
    2. The Headers
      1. Accept
      2. Accept-Charset
      3. Accept-Encoding
      4. Accept-Language
      5. Accept-Ranges
      6. Age
      7. Allow
      8. Authorization
      9. Cache-Control
      10. Connection
      11. Content-Disposition
      12. Content-Encoding
      13. Content-Language
      14. Content-Length
      15. Content-Location
      16. Content-MD5
      17. Content-Range
      18. Content-Type
      19. Cookie
      20. Date
      21. ETag
      22. Expect
      23. Expires
      24. From
      25. Host
      26. If-Match
      27. If-Modified-Since
      28. If-None-Match
      29. If-Range
      30. If-Unmodified-Since
      31. Last-Modified
      32. Link
      33. Link-Template
      34. Location
      35. Max-Forwards
      36. Pragma
      37. Prefer
      38. Preference-Applied
      39. Proxy-Authenticate
      40. Proxy-Authorization
      41. Range
      42. Referer
      43. Retry-After
      44. Set-Cookie
      45. Slug
      46. TE
      47. Trailer
      48. Transfer-Encoding
      49. Upgrade
      50. User-Agent
      51. Vary
      52. Via
      53. Warning
      54. WWW-Authenticate
  20. C. An API Designer’s Guide to the Fielding Dissertation
    1. Architectural Properties of the Web
      1. Low Entry-Barrier
      2. Extensibility
      3. Distributed Hypermedia
      4. Internet-Scale
      5. APIs Are Not (Quite) the Web
    2. Interface Constraints
      1. Identification of Resources
      2. Manipulation of Resources Through Representations
      3. Self-Descriptive Messages
      4. The Hypermedia Constraint
    3. Architectural Constraints
      1. Client-Server
      2. Statelessness
      3. Caching
      4. Uniform Interface
      5. Layered System
      6. Code on Demand
    4. Summary
    5. Conclusion
  21. Glossary
  22. Index
  23. Colophon
  24. Copyright

Product information

  • Title: RESTful Web APIs
  • Author(s): Leonard Richardson, Mike Amundsen, Sam Ruby
  • Release date: September 2013
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9781449359737