REST API Design Rulebook by Masse, Mark -- Read -- Imperial Library of Trantor

Index

REST API Design Rulebook

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 O’Reilly Media, Inc. Technical Reviewers Colleagues The REST Community Stuart Rackham Personal

1. Introduction

Hello World Wide Web Web Architecture

Client–Server 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 resource’s available interactions

Response Status Codes

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 resource’s 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

← Prev
Back
Next →

← Prev
Back
Next →