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

Appendix A. My First REST API

I designed my first REST API shortly after joining Starwave in June of 1997.

While working as a programmer in the Sports Engineering group, I was tasked with developing a new Java applet for a web page on the NASCAR Online website. The Race Tracker applet was designed to display the status of the lead cars during a live race event. Once loaded in the user’s web browser, the applet needed to continually fetch the current race status data from a server hosted by Starwave. At that time, Java applets could use either a raw socket or HTTP to access data on remote servers. However, if the applet’s requests needed to cross over the Internet, or even just pass through firewalls, HTTP was the only real option.^[51] In other words, the Java applet needed to talk to a Web API.

By the time I joined the company, the foundations for delivering this type of data over the Web had already been established by Starwave’s team of talented software engineers. Leveraging a proprietary, Java 1.1-based, automated, real-time wire feed processing and publishing system known as “Bulldog,” the server side of my task was to create a new web page template that would access and format the race data to be displayed by the applet. For a given live race event, Bulldog pulled in the data from a wire feed, created Java objects based on the data, then published the objects through my new template to constantly update a plain text file hosted on a standard web server.

These text files, each ...