RESTful Web APIs

Appendix B. The Header Codex

HTTP headers are bits of metadata that describe the protocol semantics of an HTTP request or response. Some headers, like If-None-Match, are used only in requests. They’re the client’s way of telling the server how to handle the request. Some, like ETag, are used only in responses. They’re the server’s way of conveying information about how the request was processed, or information about the underlying resource that’s not present in the representation. Some headers can be used either in a request or response, like the all-important Content-Type, which contains the media type of the entity-body.

There are two excellent guides to the standard HTTP headers. One’s in RFC 2616, the HTTP standard itself, and the other’s in print, in Appendix C of HTTP: The Definitive Guide by David Gourley and Brian Totty (O’Reilly). In this appendix, I’m giving a somewhat perfunctory description of the standard HTTP headers, with an eye toward their use in RESTful APIs, as opposed to other HTTP-based applications like websites and HTTP proxies.

Custom HTTP Headers

Creating a new HTTP method or status code is a very big deal. It basically requires writing an RFC. But anyone who runs an HTTP server is allowed to define their own HTTP headers. AtomPub defines an HTTP header called Slug (covered in an upcoming section). Amazon defines headers like X-amz-acl and X-amz-date for its S3 API.

In RESTful Web Services, I gave some advice for when to define a custom HTTP header and what ...