diff --git a/SUMMARY.md b/SUMMARY.md index 1c3f326..56e5103 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -23,9 +23,8 @@ * [Caching](protocol/caching.md) * [Message](message/README.md) * [Message Formats](message/message-formats.md) + * [Error Reporting](message/error-reporting.md) * [Content Negotiation](message/content-negotiation.md) - * [Siren](message/siren.md) - * [Error Reporting](message/error-reporting.md) * [JSON](message/json.md) * [Evolution](evolution/README.md) * [Changes and Versioning](evolution/versioning.md) diff --git a/message/content-negotiation.md b/message/content-negotiation.md index e69de29..d02ebfa 100644 --- a/message/content-negotiation.md +++ b/message/content-negotiation.md @@ -0,0 +1,27 @@ +# Content Negotiation +Every API MUST implement and every API Consumer MUST use [HTTP content negotiation](https://tools.ietf.org/html/rfc7231#section-3.4) where a representation of a resource is requested. + +> NOTE: The content negotiation plays the key role in evolving an API, **change management and versioning**. + +#### Example +A client is programmed to understand the `application/vnd.example.resource+json; version=2` message format semantics. The client requests a representation of the `/greeting` resource in desired the media type (including its version) from the server: + +``` +GET /greeting HTTP/1.1 +Accept: application/vnd.example.resource+json; version=2 +... +``` + +The server is able to provide only a newer version of the requested media type `version=2.1.3`. But since the newer version is backward compatible with the requested `version=2` (related: Changes & Versioning) it is able to satisfy the request and responds: + +``` +HTTP/1.1 200 OK +Content-Type: application/vnd.example.resource+json; version=2.1.3 +... +``` + +> NOTE: A server that doesn't have the requested representation media type available MUST respond with the HTTP Status Code **406 Not Acceptable**. +> +> NOTE: A server MAY have multiple choices available and MAY respond with the **300 Multiple Choices** response. In which case client SHOULD choose from the presented choices. +> +> You can read more about content negotiation at [MDN Content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation). diff --git a/protocol/content-negotiation.md b/protocol/content-negotiation.md deleted file mode 100644 index d02ebfa..0000000 --- a/protocol/content-negotiation.md +++ /dev/null @@ -1,27 +0,0 @@ -# Content Negotiation -Every API MUST implement and every API Consumer MUST use [HTTP content negotiation](https://tools.ietf.org/html/rfc7231#section-3.4) where a representation of a resource is requested. - -> NOTE: The content negotiation plays the key role in evolving an API, **change management and versioning**. - -#### Example -A client is programmed to understand the `application/vnd.example.resource+json; version=2` message format semantics. The client requests a representation of the `/greeting` resource in desired the media type (including its version) from the server: - -``` -GET /greeting HTTP/1.1 -Accept: application/vnd.example.resource+json; version=2 -... -``` - -The server is able to provide only a newer version of the requested media type `version=2.1.3`. But since the newer version is backward compatible with the requested `version=2` (related: Changes & Versioning) it is able to satisfy the request and responds: - -``` -HTTP/1.1 200 OK -Content-Type: application/vnd.example.resource+json; version=2.1.3 -... -``` - -> NOTE: A server that doesn't have the requested representation media type available MUST respond with the HTTP Status Code **406 Not Acceptable**. -> -> NOTE: A server MAY have multiple choices available and MAY respond with the **300 Multiple Choices** response. In which case client SHOULD choose from the presented choices. -> -> You can read more about content negotiation at [MDN Content negotiation](https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation).