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-01 15:37:13 +00:00
parent 2d4c7879a1
commit b5806e2a26
2 changed files with 17 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
SUMMARY.md
View File

@@ -20,7 +20,7 @@
* [TLS](protocol/tls.md)
* [Know your HTTP](protocol/know-your-http.md)
* [Separate Concerns](protocol/separate-concerns.md)
* [Content Negotiation ](protocol/content-negotiation.md)
* [Content Negotiation](protocol/content-negotiation.md)
* [Request Methods](protocol/use-appropriate-methods.md)
* [Status Codes](protocol/use-appropriate-status-codes.md)
* Caching

17
protocol/separate-concerns.md
View File

@@ -1,2 +1,17 @@
# Separate Concerns
xx
Every API using HTTP/S API MUST clearly follow the concern separation of a HTTP message:
1. A _resource identifier_–URI MUST be used to indicate **identity** only (related: [Content Negotiation](protocol/content-negotiation), [Changes and Versioning](core-principles/versioning.md))
1. _HTTP request method_ MUST be used to communicate the **action semantics** (intent and safety)
1. _HTTP response status_ code MUST be used to communicate the **information about the result** of the attempt to understand and satisfy the request
1. _HTTP message body_ MUST be used to transfer the **message content**
1. _HTTP message headers_ MUST be used to transfer the **metadata** about the message and its content
1. _URI query parameter_ SHOULD NOT be used to transfer metadata where possible
---
> _Keep things simple while designing by separating the concerns between the different parts of the request and response cycle. Keeping simple rules here allows for greater focus on larger and harder problems._
>
> _Requests and responses will be made to address a particular resource or collection. Use the path to indicate identity, the body to transfer the contents and headers to communicate metadata. Query params may be used as a means to pass header information also in edge cases, but headers are preferred as they are more flexible and can convey more diverse information._
>
> _– [Heroku HTTP API Design Guide](https://geemus.gitbooks.io/http-api-design/content/en/foundations/separate-concerns.html)_