REST API Design Rulebook

Chapter 3. Interaction Design with HTTP

HTTP/1.1

REST APIs embrace all aspects of the HyperText Transfer Protocol, version 1.1^[23] (HTTP/1.1) including its request methods, response codes, and message headers.

This book divides its coverage of HTTP between two chapters, with this chapter discussing request methods and response status codes. Incorporating metadata in a REST API design, with HTTP’s request and response headers, is the subject of Chapter 4.

Note

A few of this chapter’s examples use curl, the command-line, open-source web client that is available for most modern development platforms. For some common REST API-related development tasks, curl has some advantages over the browser. Specifically, curl allows easy access to HTTP’s full feature set and it is scriptable, meaning that programmers can write simple shell scripts or batch files containing curl commands to test or use a REST API.

Request Methods

Clients specify the desired interaction method in the Request-Line part of an HTTP request message. RFC 2616 defines the Request-Line syntax as shown below:

Request-Line   = Method SP Request-URI SP HTTP-Version CRLF

Each HTTP method has specific, well-defined semantics within the context of a REST API’s resource model. The purpose of GET is to retrieve a representation of a resource’s state. HEAD is used to retrieve the metadata associated with the resource’s state. PUT should be used to add a new resource to a store or update a resource. DELETE removes a resource from its parent. ...