RESTful Web APIs. Services for a Changing World

Spis treści książki

• RESTful Web APIs
• Dedication
• Dedication
• Foreword
• Introduction
  • Duplication of Effort
  • Hypermedia Is Hard
  • Whats in This Book?
  • Whats 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
  • Acknowledgments
• 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 Mapmakers 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 Cant Find a Domain-Specific Design, Dont Make One
  • Kinds of API Clients
    • Human-Driven Clients
    • Automated Clients
      • The crawler
      • The monitor
      • The script
      • The agent
• 6. The Collection Pattern
  • Whats a Collection?
    • Collections Link to Items
  • Collection+JSON
    • Representing the Items
      • An items permanent link
      • An items data
      • An items 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 Doesnt Everyone Use AtomPub?
  • The Semantic Challenge: How Are We Doing?
• 7. Pure-Hypermedia Designs
  • Why HTML?
  • HTMLs 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
  • HTMLs 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?
  • Whats 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 Doesnt 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
    • Dont Fall into the Collection Trap
    • Dont Start with the Representation Format
    • URL Design Doesnt 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 isnt special
      • Have an end-of-life plan
    • Dont Keep All the Hypermedia in One Place
  • Adding Hypermedia to an Existing API
    • Fixing Up an XML-Based API
    • Is It Worth It?
  • Alices 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 Designers 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
• Colophon
• Copyright

pokaż cały spis treści

ukryj recenzje