You are previewing REST API Design Rulebook.
O'Reilly logo
REST API Design Rulebook

Book Description

The basic rules of REST APIs - "many nouns, few verbs, stick with HTTP" - seem easy, but that simplicity and power require discipline to work smoothly. This brief guide provides next steps for implementing complex projects on simple and extensible foundations.

Table of Contents

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