REST API Design Rulebook. Designing Consistent RESTful Web Service Interfaces Mark Masse

Spis treści ebooka

• REST API Design Rulebook
  • SPECIAL OFFER: Upgrade this ebook with OReilly
  • Preface
    • Greetings Program!
    • Conventions Used in This Book
    • Using Code Examples
    • Safari Books Online
    • How to Contact Us
    • Acknowledgments
      • Tim Berners-Lee
      • Roy Fielding
      • Leonard Richardson
      • OReilly Media, Inc.
      • Technical Reviewers
      • Colleagues
      • The REST Community
      • Stuart Rackham
      • Personal
  • 1. Introduction
    • Hello World Wide Web
    • Web Architecture
      • ClientServer
      • Uniform Interface
        • Identification of resources
        • Manipulation of resources through representations
        • Self-descriptive messages
        • Hypermedia as the engine of application state (HATEOAS)
      • Layered System
      • Cache
      • Stateless
      • Code-On-Demand
    • Web Standards
    • REST
    • REST APIs
    • REST API Design
      • Rules
      • WRML
    • Recap
  • 2. Identifier Design with URIs
    • URIs
    • URI Format
      • Rule: Forward slash separator (/) must be used to indicate a hierarchical relationship
      • Rule: A trailing forward slash (/) should not be included in URIs
      • Rule: Hyphens (-) should be used to improve the readability of URIs
      • Rule: Underscores (_) should not be used in URIs
      • Rule: Lowercase letters should be preferred in URI paths
      • Rule: File extensions should not be included in URIs
    • URI Authority Design
      • Rule: Consistent subdomain names should be used for your APIs
      • Rule: Consistent subdomain names should be used for your client developer portal
    • Resource Modeling
    • Resource Archetypes
      • Document
      • Collection
      • Store
      • Controller
    • URI Path Design
      • Rule: A singular noun should be used for document names
      • Rule: A plural noun should be used for collection names
      • Rule: A plural noun should be used for store names
      • Rule: A verb or verb phrase should be used for controller names
      • Rule: Variable path segments may be substituted with identity-based values
      • Rule: CRUD function names should not be used in URIs
    • URI Query Design
      • Rule: The query component of a URI may be used to filter collections or stores
      • Rule: The query component of a URI should be used to paginate collection or store results
    • Recap
  • 3. Interaction Design with HTTP
    • HTTP/1.1
    • Request Methods
      • Rule: GET and POST must not be used to tunnel other request methods
      • Rule: GET must be used to retrieve a representation of a resource
      • Rule: HEAD should be used to retrieve response headers
      • Rule: PUT must be used to both insert and update a stored resource
      • Rule: PUT must be used to update mutable resources
      • Rule: POST must be used to create a new resource in a collection
      • Rule: POST must be used to execute controllers
      • Rule: DELETE must be used to remove a resource from its parent
      • Rule: OPTIONS should be used to retrieve metadata that describes a resources available interactions
    • Response Status Codes
      • Rule: 200 (OK) should be used to indicate nonspecific success
      • Rule: 200 (OK) must not be used to communicate errors in the response body
      • Rule: 201 (Created) must be used to indicate successful resource creation
      • Rule: 202 (Accepted) must be used to indicate successful start of an asynchronous action
      • Rule: 204 (No Content) should be used when the response body is intentionally empty
      • Rule: 301 (Moved Permanently) should be used to relocate resources
      • Rule: 302 (Found) should not be used
      • Rule: 303 (See Other) should be used to refer the client to a different URI
      • Rule: 304 (Not Modified) should be used to preserve bandwidth
      • Rule: 307 (Temporary Redirect) should be used to tell clients to resubmit the request to another URI
      • Rule: 400 (Bad Request) may be used to indicate nonspecific failure
      • Rule: 401 (Unauthorized) must be used when there is a problem with the clients credentials
      • Rule: 403 (Forbidden) should be used to forbid access regardless of authorization state
      • Rule: 404 (Not Found) must be used when a clients URI cannot be mapped to a resource
      • Rule: 405 (Method Not Allowed) must be used when the HTTP method is not supported
      • Rule: 406 (Not Acceptable) must be used when the requested media type cannot be served
      • Rule: 409 (Conflict) should be used to indicate a violation of resource state
      • Rule: 412 (Precondition Failed) should be used to support conditional operations
      • Rule: 415 (Unsupported Media Type) must be used when the media type of a requests payload cannot be processed
      • Rule: 500 (Internal Server Error) should be used to indicate API malfunction
    • Recap
  • 4. Metadata Design
    • HTTP Headers
      • Rule: Content-Type must be used
      • Rule: Content-Length should be used
      • Rule: Last-Modified should be used in responses
      • Rule: ETag should be used in responses
      • Rule: Stores must support conditional PUT requests
      • Rule: Location must be used to specify the URI of a newly created resource
      • Rule: Cache-Control, Expires, and Date response headers should be used to encourage caching
      • Rule: Cache-Control, Expires, and Pragma response headers may be used to discourage caching
      • Rule: Caching should be encouraged
      • Rule: Expiration caching headers should be used with 200 (OK) responses
      • Rule: Expiration caching headers may optionally be used with 3xx and 4xx responses
      • Rule: Custom HTTP headers must not be used to change the behavior of HTTP methods
    • Media Types
      • Media Type Syntax
      • Registered Media Types
      • Vendor-Specific Media Types
    • Media Type Design
      • Rule: Application-specific media types should be used
        • Media Type Format Design
        • Media Type Schema Design
        • Media Type Schema Versioning
      • Rule: Media type negotiation should be supported when multiple representations are available
      • Rule: Media type selection using a query parameter may be supported
    • Recap
  • 5. Representation Design
    • Message Body Format
      • Rule: JSON should be supported for resource representation
      • Rule: JSON must be well-formed
      • Rule: XML and other formats may optionally be used for resource representation
      • Rule: Additional envelopes must not be created
    • Hypermedia Representation
      • Rule: A consistent form should be used to represent links
      • Rule: A consistent form should be used to represent link relations
      • Rule: A consistent form should be used to advertise links
      • Rule: A self link should be included in response message body representations
      • Rule: Minimize the number of advertised entry point API URIs
      • Rule: Links should be used to advertise a resources available actions in a state-sensitive manner
    • Media Type Representation
      • Rule: A consistent form should be used to represent media type formats
      • Rule: A consistent form should be used to represent media type schemas
        • Schema Representation
        • Field Representation
        • Constraint Representation
        • Link Formula Representation
        • Document Schema Representation
        • Container Schema Representation
        • Collection Schema Representation
        • Store Schema Representation
    • Error Representation
      • Rule: A consistent form should be used to represent errors
      • Rule: A consistent form should be used to represent error responses
      • Rule: Consistent error types should be used for common error conditions
    • Recap
  • 6. Client Concerns
    • Introduction
    • Versioning
      • Rule: New URIs should be used to introduce new concepts
      • Rule: Schemas should be used to manage representational form versions
      • Rule: Entity tags should be used to manage representational state versions
    • Security
      • Rule: OAuth may be used to protect resources
      • Rule: API management solutions may be used to protect resources
    • Response Representation Composition
      • Rule: The query component of a URI should be used to support partial responses
      • Rule: The query component of a URI should be used to embed linked resources
    • Processing Hypermedia
    • JavaScript Clients
      • Rule: JSONP should be supported to provide multi-origin read access from JavaScript
      • Rule: CORS should be supported to provide multi-origin read/write access from JavaScript
    • Recap
  • 7. Final Thoughts
    • State of the Art
    • Uniform Implementation
      • Principle: REST API designs differ more than necessary
      • Principle: A REST API should be designed, not coded
      • Principle: Programmers and their organizations benefit from consistency
      • Principle: A REST API should be created using a GUI tool
    • Recap
  • A. My First REST API
  • About the Author
  • SPECIAL OFFER: Upgrade this ebook with OReilly

pokaż cały spis treści

ukryj recenzje