300 Multiple Choices: When a Resource Has Many Representations
Accept-Language or Accept-Encoding) to automatically select the appropriate version.
When Is 300 Used?
300 is rarely used in practice. It is a fallback for cases where content negotiation fails or where the server wants to present a menu of options to the user. Typical scenarios include:
- Multiple file formats β a resource available as HTML, JSON, XML, or PDF.
- Multiple languages β the same content in English, Spanish, French, etc.
- Multiple encodings β plain text, gzip-compressed, etc.
- Ambiguous URI β when the requested URI maps to several resources.
How the Server Responds
The server can respond with a list of alternatives in the body, typically in HTML or plain text, with a Location header pointing to a default choice, and the body containing the full list.
ClientβDriven Content Negotiation
In many cases, the server uses Accept-* headers to automatically choose the best representation without a 300. For example:
Accept-Language: esβ server sends Spanish version.Accept: application/jsonβ server sends JSON.
If the server cannot determine a preferred choice (e.g., the headers are missing or conflicting), it may respond with 300 and let the client choose.
Why 300 Is Rarely Used
- Content negotiation is automatic β most modern servers and clients handle negotiation via headers, so 300 is unnecessary.
- Better alternatives β using
Varyand cache headers is more efficient. - User experience β showing a menu to the user is often clunky; redirecting to a default is preferred.
Best Practices
- Avoid using 300 β prefer automated content negotiation.
- If you must use it, provide a clear list of choices and a default
Location. - Use
Varyheader β to inform caches that the response varies based on request headers. - For APIs, use 200 with a JSON list of available representations rather than 300.
Frequently Asked Questions
Is 300 Multiple Choices the same as 301?
No. 301 is a permanent redirect to a single specific URI. 300 is a menu of multiple choices, not a redirect to one.
What should a client do when it receives 300?
Ideally, the client should present the list of choices to the user or automatically select one based on its preferences (if it has configured priorities for language, format, etc.). However, many clients simply follow the Location header if present.
Can 300 be cached?
Yes, but the cache must respect the Vary header to ensure different representations are served correctly.