Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

Updates SUMMARY.md

Browse Source 
Auto commit by GitBook Editor
This commit is contained in:
apidesigner
2017-02-07 13:30:40 +00:00
parent 0d39915c1d
commit ee473a8cef
3 changed files with 28 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
SUMMARY.md
View File

@@ -23,9 +23,8 @@
* [Caching](protocol/caching.md) * [Caching](protocol/caching.md)
* [Message](message/README.md) * [Message](message/README.md)
* [Message Formats](message/message-formats.md) * [Message Formats](message/message-formats.md)
* [Content Negotiation](message/content-negotiation.md)
* [Siren](message/siren.md)
* [Error Reporting](message/error-reporting.md) * [Error Reporting](message/error-reporting.md)
* [Content Negotiation](message/content-negotiation.md)
* [JSON](message/json.md) * [JSON](message/json.md)
* [Evolution](evolution/README.md) * [Evolution](evolution/README.md)
* [Changes and Versioning](evolution/versioning.md) * [Changes and Versioning](evolution/versioning.md)

27
message/content-negotiation.md
View File

@@ -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).

27
protocol/content-negotiation.md
View File

@@ -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).