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

Chapter 7. Final Thoughts

State of the Art

Today, implementing our REST API designs is harder than it ought to be. The tools and frameworks that aim to support REST API developers have room for improvement. Many of the programming language-centric REST API development frameworks were originally created to help build web applications. These frameworks seem to suggest that REST APIs are similar enough to web applications that they should be cast from the same mold.

By repurposing the web application’s controller paradigm, many of today’s frameworks provide support for using URI templates to route inbound client requests to handler-style methods or functions. In recognition of the fact that developers don’t want to code web page templates to format their REST API’s data, most of the frameworks offer built-in XML and JSON-based serialization and deserialization of the server’s objects to and from an HTTP message’s body.

Today, there is no unanimous winner among the various REST API development framework candidates. The selection amounts to personal (or organizational) preference of programming language and platform.

Unfortunately, most of the current REST API development frameworks lack direct support for:

Natural separation of the resource model from the server’s implementation model
Uniform, cross-format hypermedia structures
Automated HATEOAS; based on current state, determining which links should be provided in a response
Media type schema validation and versioning
Both partial and dynamically ...