REST API Design Rulebook

REST API Design Rulebook

by Mark Masse
Released October 2011
Publisher(s): O'Reilly Media, Inc.
ISBN: 9781449310509

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.

Buy on Amazon Buy on ebooks.com
Start your free trial

Book description

In todayâ??s market, where rival web services compete for attention, a well-designed REST API is a must-have feature. This concise book presents a set of API design rules, drawn primarily from best practices that stick close to the Webâ??s REST architectural style. Along with rules for URI design and HTTP use, youâ??ll learn guidelines for media types and representational forms.

REST APIs are ubiquitous, but few of them follow a consistent design methodology. Using these simple rules, you will design web service APIs that adhere to recognized web standards. To assist you, author Mark Massé introduces the Web Resource Modeling Language (WRML), a conceptual framework he created for the design and implementation of REST APIs.

  • Learn design rules for addressing resources with URIs
  • Apply design principles to HTTPâ??s request methods and response status codes
  • Work with guidelines for conveying metadata through HTTP headers and media types
  • Get design tips to address the needs of client programs, including the special needs of browser-based JavaScript clients
  • Understand why REST APIs should be designed and configured, not coded

Publisher resources

View/Submit Errata

Table of contents

  1. Dedication
  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. Copyright

Product information

  • Title: REST API Design Rulebook
  • Author(s): Mark Masse
  • Release date: October 2011
  • Publisher(s): O'Reilly Media, Inc.
  • ISBN: 9781449310509