RESTful Web APIs
Services for a Changing World
Published on 12. September 2013
406 pages
978-1-4493-5974-4 (ISBN)
Description
The popularity of REST in recent years has led to tremendous growth in almost-RESTful APIs that dont include many of the architectures benefits. With this practical guide, youll 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 worlds most successful distributed computing system: the World Wide Web.Youll 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 hypermediaUnderstand how hypermedia ties representations together into a coherent APIDiscover how XMDP and ALPS profile formats can help you meet the Web API "e;semantic challenge"e;Learn close to two-dozen standardized hypermedia data formatsApply best practices for using HTTP in API implementationsCreate Web APIs with the JSON-LD standard and other the Linked Data approachesUnderstand the CoAP protocol for using REST in embedded systems
More details
Other editions
Additional editions
Leonard Richardson | Mike Amundsen | Sam Ruby
RESTful Web APIs
Book
10/2013
1st Edition
O'Reilly
€45.00
Article not available at the moment
Content
- Intro
- Copyright
- Table of Contents
- 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
- Conventions Used in This Book
- Using Code Examples
- Safari® Books Online
- How to Contact Us
- Acknowledgments
- Chapter 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
- 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
- GET
- DELETE
- Idempotence
- POST-to-Append
- PUT
- PATCH
- LINK and UNLINK
- HEAD
- OPTIONS
- Overloaded POST
- 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
- Guiding the Request
- Promises About the Response
- Workflow Control
- 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
- 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
- Chapter 6. The Collection Pattern
- What's a Collection?
- Collections Link to Items
- Collection+JSON
- Representing the Items
- 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?
- Chapter 7. Pure-Hypermedia Designs
- Why HTML?
- HTML's Capabilities
- Hypermedia Controls
- Plug-in Application Semantics
- 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?
- Chapter 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
- Chapter 9. The Design Procedure
- Two-Step Design Procedure
- Seven-Step Design Procedure
- Step 1: List the Semantic Descriptors
- Step 2: Draw a State Diagram
- Step 3: Reconcile Names
- Step 4: Choose a Media Type
- Step 5: Write a Profile
- Step 6: Implementation
- Step 7: Publication
- 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
- 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
- Chapter 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
- 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
- Chapter 11. HTTP for APIs
- The New HTTP/1.1 Specification
- Response Codes
- Headers
- Choosing Between Representations
- Content Negotiation
- 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
- Chapter 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!
- 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 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)
- Appendix 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
- Appendix 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
