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 protocol/separate-concerns.md

Browse Source 
Auto commit by GitBook Editor
This commit is contained in:
apidesigner
2017-02-02 14:03:46 +00:00
parent 2886cfdb4b
commit fd08ac7b09
1 changed files with 29 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
protocol/separate-concerns.md
View File

@@ -8,7 +8,35 @@ Every API using HTTP/S API MUST clearly follow the concern separation of a HTTP
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
> NOTE: Rule No.1 means there MUST be NO information about the media type or version of resource in the URI (e.g. `/greeting.json` or `/v2.1.3/greeting` are **illegal**).
#### Example 1
The rule
> A resource identifier–URI MUST be used to indicate identity only
implies there MUST be NO information about the media type or version of resource in the URI. For example URIs `/greeting.json` or `/v2.1.3/greeting` are **illegal** as they are not used for identification of a resource only but they convey the information about representation format and version.
#### Example 2
The rule
> HTTP message body MUST be used to transfer the message content
implies an HTTP GET request MUST NOT use HTTP message body to identify the resource. For example a request:
```
GET /greeting HTTP/1.1
Content-Type: application/json
...
{
"filter": "string"
"depth": 3
}
```
is **illegal**. To express identity use URI and query parameters instead e.g. `/greeting?filter=string&depth=3`.
---