300 Multiple Choices

300 Multiple Choices is the first of the 3xx series, which are all used for redirection.

300 should be emitted specifically when a resource can redirect to more than one location, and it wants the user to decide which one.

Support for 300 is scarce. In the past both the URI and Alternates HTTP headers were suggested to tell a client which resource to choose, but RFC7231 currently recommends the Link header.

Example

HTTP/1.1 300 Multiple Choices
Server: curveball/0.3.1
Access-Control-Allow-Headers: Content-Type,User-Agent
Access-Control-Allow-Origin: *
Link: </foo> rel="alternate"
Link: </bar> rel="alternate"
Content-Type: text/html
Location: /foo

This example lists /foo and /bar as potential choices a user could make. The response also suggests a default with the Location header. This is optional.

Usage

In my testing neither Chrome nor Firefox have way to deal with 300 responses.

However, it is possible for a server to just return a text/html body, listing both choices and allowing a user to click to the resource they want.

I also tested the Location header. If it’s present, Firefox will immediately redirect to that location, and Chrome ignores it.

However, I think it’s perfectly fine to use this status in an API, and write a custom client to do something with this response.

If you are building a Hypermedia service, you could also respond with for example a HAL document listing the various choices, although I would make sure that the alternate links appear both in the HTTP Link header, as well as the HAL _links object.

References

HTTP series

This article is part of an ongoing series about the HTTP protocol.

If you want to follow along as I write them, you can Subscribe to my Atom feed or Mailing list.

Archive

Web mentions