Multiple Choices

Server perspective

Use 300 when more than one representation or target is valid and the client should pick the preferred one.

When to use

• •Return 300 for reactive negotiation when the response should list alternatives instead of choosing for the client
• •If there is a preferred target, you may also include Location to point at that preference
• •A resource is available in multiple representations and the server wants the client to choose
• •Different formats, languages, or variants are available and automatic selection is not desired
• •The server can provide a list of alternatives instead of forcing one redirect target

How to respond

• •Include a machine- or human-readable list of alternatives in the response body
• •Keep each alternative specific enough that the client can make a meaningful choice
• •Expose machine-readable alternatives via Link headers with rel=alternate when the client can act on them programmatically

Headers to consider

• •Location
• •Link

Response body

• •Include a list of alternative representations or URIs; Location is optional, not mandatory

Server-side pitfalls

• •Do not use 300 as a generic redirect when there is only one real target
• •Do not expect clients to understand an undocumented custom alternatives format automatically
• •There is one clearly preferred redirect target; use 301, 302, 307, or 308 as appropriate
• •The server can confidently choose the best representation and return 200
• •You need to indicate the requested representation is unacceptable; use 406

Examples