book

REST API Design Rulebook

by Mark Masse

October 2011

Intermediate to advanced

112 pages

2h 39m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Greetings Program!Conventions Used in This BookUsing Code ExamplesSafari® Books OnlineHow to Contact UsAcknowledgmentsTim Berners-LeeRoy FieldingLeonard RichardsonO’Reilly Media, Inc.Technical ReviewersColleaguesThe REST CommunityStuart RackhamPersonal
Hello World Wide WebWeb ArchitectureClient–ServerUniform InterfaceIdentification of resourcesManipulation of resources through representationsSelf-descriptive messagesHypermedia as the engine of application state (HATEOAS)Layered SystemCacheStatelessCode-On-DemandWeb StandardsRESTREST APIsREST API DesignRulesWRMLRecap
URIsURI FormatRule: Forward slash separator (/) must be used to indicate a hierarchical relationshipRule: A trailing forward slash (/) should not be included in URIsRule: Hyphens (-) should be used to improve the readability of URIsRule: Underscores (_) should not be used in URIsRule: Lowercase letters should be preferred in URI pathsRule: File extensions should not be included in URIsURI Authority DesignRule: Consistent subdomain names should be used for your APIsRule: Consistent subdomain names should be used for your client developer portalResource ModelingResource ArchetypesDocumentCollectionStoreControllerURI Path DesignRule: A singular noun should be used for document namesRule: A plural noun should be used for collection namesRule: A plural noun should be used for store namesRule: A verb or verb phrase should be used for controller namesRule: Variable path segments may be substituted with identity-based valuesRule: CRUD function names should not be used in URIsURI Query DesignRule: The query component of a URI may be used to filter collections or storesRule: The query component of a URI should be used to paginate collection or store resultsRecap
HTTP/1.1Request MethodsRule: GET and POST must not be used to tunnel other request methodsRule: GET must be used to retrieve a representation of a resourceRule: HEAD should be used to retrieve response headersRule: PUT must be used to both insert and update a stored resourceRule: PUT must be used to update mutable resourcesRule: POST must be used to create a new resource in a collectionRule: POST must be used to execute controllersRule: DELETE must be used to remove a resource from its parentRule: OPTIONS should be used to retrieve metadata that describes a resource’s available interactionsResponse Status CodesRule: 200 (“OK”) should be used to indicate nonspecific successRule: 200 (“OK”) must not be used to communicate errors in the response bodyRule: 201 (“Created”) must be used to indicate successful resource creationRule: 202 (“Accepted”) must be used to indicate successful start of an asynchronous actionRule: 204 (“No Content”) should be used when the response body is intentionally emptyRule: 301 (“Moved Permanently”) should be used to relocate resourcesRule: 302 (“Found”) should not be usedRule: 303 (“See Other”) should be used to refer the client to a different URIRule: 304 (“Not Modified”) should be used to preserve bandwidthRule: 307 (“Temporary Redirect”) should be used to tell clients to resubmit the request to another URIRule: 400 (“Bad Request”) may be used to indicate nonspecific failureRule: 401 (“Unauthorized”) must be used when there is a problem with the client’s credentialsRule: 403 (“Forbidden”) should be used to forbid access regardless of authorization stateRule: 404 (“Not Found”) must be used when a client’s URI cannot be mapped to a resourceRule: 405 (“Method Not Allowed”) must be used when the HTTP method is not supportedRule: 406 (“Not Acceptable”) must be used when the requested media type cannot be servedRule: 409 (“Conflict”) should be used to indicate a violation of resource stateRule: 412 (“Precondition Failed”) should be used to support conditional operationsRule: 415 (“Unsupported Media Type”) must be used when the media type of a request’s payload cannot be processedRule: 500 (“Internal Server Error”) should be used to indicate API malfunctionRecap
HTTP HeadersRule: Content-Type must be usedRule: Content-Length should be usedRule: Last-Modified should be used in responsesRule: ETag should be used in responsesRule: Stores must support conditional PUT requestsRule: Location must be used to specify the URI of a newly created resourceRule: Cache-Control, Expires, and Date response headers should be used to encourage cachingRule: Cache-Control, Expires, and Pragma response headers may be used to discourage cachingRule: Caching should be encouragedRule: Expiration caching headers should be used with 200 (“OK”) responsesRule: Expiration caching headers may optionally be used with 3xx and 4xx responsesRule: Custom HTTP headers must not be used to change the behavior of HTTP methodsMedia TypesMedia Type SyntaxRegistered Media TypesVendor-Specific Media TypesMedia Type DesignRule: Application-specific media types should be usedMedia Type Format DesignMedia Type Schema DesignMedia Type Schema VersioningRule: Media type negotiation should be supported when multiple representations are availableRule: Media type selection using a query parameter may be supportedRecap
Message Body FormatRule: JSON should be supported for resource representationRule: JSON must be well-formedRule: XML and other formats may optionally be used for resource representationRule: Additional envelopes must not be createdHypermedia RepresentationRule: A consistent form should be used to represent linksRule: A consistent form should be used to represent link relationsRule: A consistent form should be used to advertise linksRule: A self link should be included in response message body representationsRule: Minimize the number of advertised “entry point” API URIsRule: Links should be used to advertise a resource’s available actions in a state-sensitive mannerMedia Type RepresentationRule: A consistent form should be used to represent media type formatsRule: A consistent form should be used to represent media type schemasSchema RepresentationField RepresentationConstraint RepresentationLink Formula RepresentationDocument Schema RepresentationContainer Schema RepresentationCollection Schema RepresentationStore Schema RepresentationError RepresentationRule: A consistent form should be used to represent errorsRule: A consistent form should be used to represent error responsesRule: Consistent error types should be used for common error conditionsRecap
IntroductionVersioningRule: New URIs should be used to introduce new conceptsRule: Schemas should be used to manage representational form versionsRule: Entity tags should be used to manage representational state versionsSecurityRule: OAuth may be used to protect resourcesRule: API management solutions may be used to protect resourcesResponse Representation CompositionRule: The query component of a URI should be used to support partial responsesRule: The query component of a URI should be used to embed linked resourcesProcessing HypermediaJavaScript ClientsRule: JSONP should be supported to provide multi-origin read access from JavaScriptRule: CORS should be supported to provide multi-origin read/write access from JavaScriptRecap
State of the ArtUniform ImplementationPrinciple: REST API designs differ more than necessaryPrinciple: A REST API should be designed, not codedPrinciple: Programmers and their organizations benefit from consistencyPrinciple: A REST API should be created using a GUI toolRecap

Content preview from REST API Design Rulebook

REST API Design Rulebook

Mark Masse

Editor

Simon St. Laurent

Revision History
2011-10-17	First release

O’Reilly books may be purchased for educational, business, or sales promotional use. Online editions are also available for most titles (http://my.safaribooksonline.com). For more information, contact our corporate/institutional sales department: (800) 998-9938 or corporate@oreilly.com.

Nutshell Handbook, the Nutshell Handbook logo, and the O’Reilly logo are registered trademarks of O’Reilly Media, Inc. REST API Design Rulebook, the image of a crested shriketit, and related trade dress are trademarks of O’Reilly Media, Inc.

Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks. Where those designations appear in this book, and O’Reilly Media, Inc., was aware of a trademark claim, the designations have been printed in caps or initial caps.

While every precaution has been taken in the preparation of this book, the publisher and authors assume no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.

O’Reilly Media

1005 Gravenstein Highway North

Sebastopol, CA 95472

2013-04-01T11:04:50-07:00

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Start your free trial

Publisher Resources

ISBN: 9781449317904Errata Page

REST API Design Rulebook

by Mark Masse

REST API Design Rulebook

Mark Masse

Editor

Simon St. Laurent

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

You might also like

Mastering API Architecture

Understanding APIs and RESTful APIs Crash Course

Building Event-Driven Microservices

Design and Build Great Web APIs

Publisher Resources

REST API Design Rulebook

Mark Masse

Editor

Simon St. Laurent

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,and much more.

You might also like

Mastering API Architecture

Understanding APIs and RESTful APIs Crash Course

Building Event-Driven Microservices

Design and Build Great Web APIs

Publisher Resources

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.