Posted on by & filed under Content - Highlights and Reviews, Programming & Development.

Few Web APIs these days don’t strive in some way to be RESTful. When designing an API, developers often focus on the CRUD (Create, Read, Update and Delete) operations that apply to their API resources, and how these map onto the four main HTTP request methods (PUT, GET, POST, DELETE).

But there are some additional often-overlooked HTTP methods that are useful for building efficient RESTful systems. These are all part of the standard interface defined by HTTP, and should feature in a RESTful API.

The HEAD and OPTIONS methods allow resources to be inspected without retrieving a representation: neither method returns an entity body, just metadata in the form of HTTP headers. Read more about these methods in Chapter 3. Interaction Design with HTTP, Request Methods in REST API Design Rulebook. The methods are useful in several ways.

Lets start with an OPTIONS request. The following shows an example OPTIONS request using curl:

The OPTIONS request method allows a client to discover how it can interact with a resource. The example response tells us that the resource exists (200 OK), which version of HTTP the server supports, and the list of HTTP methods supported by the resource (via the Allow header).

Additional headers can supply other useful metadata. For example, the Cross-Origin Resource Sharing (CORS) specification uses OPTIONS as a means to pre-flight cross-domain requests from client-side code. CORS specific response headers are used to indicate whether the request is allowed. Browsers then apply that data to permit or deny the request.

A HEAD request to the same resource then retrieves a slightly different set of metadata:

A HEAD request returns metadata about the resource rather than how we can interact with it. We can discover its size (Content-Length) and versioning information (Last-Modified, ETag). Again, additional headers might provide more context. In fact the response to a HEAD request MUST be identical to an equivalent GET request, i.e. have all of the same headers. It just returns no content.

So HEAD and OPTIONS are useful any time we don’t need the content of the resource. This includes:

  • Testing whether a resource exists and is accessible. For example, validating user-submitted links in an application (HEAD, OPTIONS)
  • Identifying which HTTP methods a resource supports, e.g. can we DELETE it or update it via a PUT? (OPTIONS)
  • Checking whether a resource has changed (HEAD). This is useful when maintaining a cached version of a resource
  • Retrieving metadata about the resource, e.g. its media type or its size, before making a possibly costly retrieval (HEAD)

Many modern web frameworks, e.g. Sinatra and Slim, will automatically add a handler for a HEAD request if you define a GET method for a resource, but OPTIONS support is rarer. Even a HEAD request might be better off handled explicitly. A framework will usually treat it like a GET but discard the generated results. Writing specific code may allow requests to be processed more efficiently and accurately.

This blog post has explained how supporting and using HEAD and OPTIONS requests gives us opportunities for creating more efficient applications.

For more details about REST, see the ebooks referenced below.

Safari Books Online has the content you need

REST continues to gain momentum as the best method for building web services, leaving many web architects to consider whether and how to include this approach in their SOA and SOAP-dominated world. Rest in Practice offers a down-to-earth explanation of REST, with techniques and examples that show you how to design and implement integration solutions using the REST architectural style.
The basic rules of REST APIs – “many nouns, few verbs, stick with HTTP” – seem easy, but that simplicity and power require discipline to work smoothly. REST API Design Rulebook provides the next steps for implementing complex REST projects on simple and extensible foundations.
SOA with REST: Principles, Patterns & Constraints for Building Enterprise Solutions with REST is the first comprehensive tutorial and reference for designing and building RESTful services as part of service-oriented solutions and in conjunction with service-oriented architecture (SOA). This book demonstrates that REST is not only a suitable medium for building truly service-oriented solutions, but also that the service-oriented architectural model is a necessary foundation for REST technology architectures to realize their full business potential.

About the author

Leigh Dodds is a freelance consultant specializing in Linked Data, Open Data and API development. Passionate about the web, open standards, and open source he enjoys exploring how to apply new technologies to create interesting products. He’s also quite fond of gaming, Lego, Minecraft and a good beer. You can reach Leigh on
Github: or on Twitter: @ldodds.


Comments are closed.