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

Overview

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