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
- RFC7231, Section 6.4.1 - 300 Multiple Choices
- RFC5988 -
Linkheader.