GitBook: [master] 69 pages modified

rest-api-guidelines/protocol/README.md

@@ -0,0 +1,4 @@
+# Protocol
+
+This section outlines the protocol-level semantics and guidelines.
+

rest-api-guidelines/protocol/http.md

@@ -0,0 +1,36 @@
+# HTTP
+
+Every API MUST support [HTTP/1.1](https://tools.ietf.org/html/rfc7230) and **MUST** adhere to its **semantic**.
+
+## HTTP Protocol Quick Start
+
+The understanding of HTTP starts with the understanding of [HTTP message](https://developer.mozilla.org/en-US/docs/Web/HTTP/Messages) and its routing.
+
+Once you are familiar with the **HTTP message structure** learn about the **HTTP request methods**, **HTTP response status codes** and **HTTP headers**.
+
+Each HTTP request method, status code, and header have its semantics defined, and every API **MUST** strictly adhere to it.
+
+Follow the [Robustness Principle](../../general-guidelines/robustness.md). Use only the HTTP request methods, response codes and HTTP headers you understand, be liberal in accepting others.
+
+## Know HTTP
+
+The following documents are great overview of the HTTP protocol and related standards:
+
+* [HTTP Headers](https://github.com/for-GET/know-your-http-well/blob/master/headers.md)
+* [HTTP Request Methods](https://github.com/for-GET/know-your-http-well/blob/master/methods.md)
+* [HTTP Response Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md)
+* [HTTP Link Relations](https://github.com/for-GET/know-your-http-well/blob/master/relations.md)
+
+Alternatively, you can download HTTP cheat sheets at [HTTP posters](https://github.com/bigcompany/know-your-http).
+
+## RFCs
+
+The HTTP protocol semantics is defined in the following RFCs:
+
+> 1. [RFC 7230, HTTP/1.1: Message Syntax and Routing](https://tools.ietf.org/html/rfc7230)
+> 2. [RFC 7231, HTTP/1.1: Semantics and Content](https://tools.ietf.org/html/rfc7231)
+> 3. [RFC 7232, HTTP/1.1: Conditional Requests](https://tools.ietf.org/html/rfc7232)
+> 4. [RFC 7233, HTTP/1.1: Range Requests](https://tools.ietf.org/html/rfc7233)
+> 5. [RFC 7234, HTTP/1.1: Caching](https://tools.ietf.org/html/rfc7234)
+> 6. [RFC 7235, HTTP/1.1: Authentication](https://tools.ietf.org/html/rfc7234)
+

rest-api-guidelines/protocol/separate-concerns.md

@@ -0,0 +1,49 @@
+# Separate Concerns
+
+Every API using HTTP/S API **MUST** precisely follow the concern separation of an HTTP message:
+
+1. A _resource identifier_–URI **MUST** be used to indicate **identity** only
+2. _HTTP request method_ **MUST** be used to communicate the **action semantics** \(intent and safety\)
+3. _HTTP response status_ code **MUST** be used to communicate the **information about the result** of the attempt to understand and satisfy the request
+4. _HTTP message body_ **MUST** be used to transfer the **message content**
+5. _HTTP message headers_ **MUST** be used to transfer the **metadata** about the message and its content
+6. _URI query parameter_ **SHOULD NOT** be used to transfer metadata
+
+## Example 1
+
+The rule
+
+> A resource identifier–URI **MUST** be used to indicate identity only
+
+implies there **MUST NOT** be any information about the representation media type, version of the resource or anything else 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 or version. URIs are not meant to carry any other information but the identifier of the resource.
+
+## 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:
+
+```text
+GET /greeting HTTP/1.1
+Content-Type: application/json
+...
+
+
+{
+    "filter": "string"
+    "depth": 3
+}
+```
+
+is **not acceptable** \(ignoring the fact that HTTP GET method shouldn't have the body\). To express identity use URI and query parameters instead e.g. `/greeting?filter=string&depth=3`.
+
+> _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)
+

rest-api-guidelines/protocol/tls.md

@@ -0,0 +1,6 @@
+# TLS
+
+Every API **MUST** require secure connections with **TLS 1.2**. That is, an API using the HTTP protocol **MUST** use **HTTPS**.
+
+Any non-TLS requests **SHOULD** be ignored. In **HTTP** environments where this is not possible, a non-TLS request **SHOULD** result in the **403 Forbidden** response.
+

rest-api-guidelines/protocol/use-appropriate-methods.md

@@ -0,0 +1,44 @@
+# Request Methods
+
+Every API **MUST** use appropriate [HTTP request methods](https://github.com/for-GET/know-your-http-well/blob/master/methods.md) for every operation.
+
+Every API designer, implementer and consumer **MUST** understand the semantic of the HTTP METHOD she is using.
+
+At a minimum everyone **MUST** be familiar with the semantics of ["Common" HTTP Request Methods](https://github.com/for-GET/know-your-http-well/blob/master/methods.md#common): **DELETE**, **GET**, **HEAD**, **PUT**, **POST** and the [**PATCH** HTTP Request Method](https://tools.ietf.org/html/rfc5789#section-2). In addition, everyone **MUST** be aware which methods are **Safe**, **Idempotent** and **Cacheable**.
+
+## Safe Methods
+
+As per HTTP specification, the **GET** and **HEAD** methods should be used only for retrieval of resource representations – and they do not update/delete the resource on the server. Both methods are said to be considered “safe“. This allows user agents to represent other methods, such as POST, PUT and DELETE, in a special way, so that the user is made aware of the fact that a possibly unsafe action is being requested – and they can update/delete the resource on the server and so should be used carefully.
+
+## Idempotent Methods
+
+The term idempotent is used more comprehensively to describe an operation that will produce the same results if executed once or multiple times. This is a beneficial property in many situations, as it means that a transaction can be repeated or retried as often as necessary without causing unintended effects. With non-idempotent operations, the algorithm may have to keep track of whether the operation was already performed or not. In HTTP specification, The methods **GET**, **HEAD**, **PUT** and **DELETE** are declared idempotent methods. Other methods OPTIONS and TRACE **SHOULD NOT** have side effects, so both are also inherently idempotent.
+
+## Cacheable Methods
+
+Request methods are considered "cacheable" if it is possible and useful to answer a current client request with a stored response from a prior request. **GET** and **HEAD** are defined to be cacheable.
+
+### Example 1
+
+> GET /user/new Description: Creates new user
+
+Using GET for unsafe non-idempotent operations is **not acceptable**.
+
+### Example 2
+
+> POST /status Description: Updates the status of a user approval request \(to “Approved” or “Rejected”\)
+
+Using the POST method for a status update is **not acceptable** \(use PATCH\).
+
+### Example 3
+
+> PUT /user Description: Creates a new user
+
+Using the PUT method for creating a new resource is **not acceptable** \(use POST\).
+
+### Example 4
+
+> PUT: /user Description: Updates some user details
+
+Using the PUT method for a partial update is **not acceptable** \(use PATCH\).
+

rest-api-guidelines/protocol/use-appropriate-status-codes.md

@@ -0,0 +1,48 @@
+# Status Codes
+
+Every API **MUST** use the appropriate [HTTP Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md) to communicate the result of a request operation.
+
+Every API designer, implementer and consumer **MUST** understand the semantic of the HTTP Status Code she is using.
+
+At a minimum everyone **MUST** be familiar with the semantics of ["Common" HTTP Status Codes](https://github.com/for-GET/know-your-http-well/blob/master/status-codes.md#common).
+
+## Example
+
+## Use Codes 4xx or 5xx to Communicate Errors
+
+A request:
+
+```text
+GET /orders/1234 HTTP/1.1
+...
+```
+
+resulting in the **200 OK** response, when the requested resource \(as identified by request URI\) couldn't be found:
+
+```text
+HTTP/1.1 200 OK
+Content-Type: application/json
+...
+
+
+{
+    "code": "NOT_FOUND_ERR_CODE"
+    "message" "Order 1234 wasn't found"
+}
+```
+
+is **not acceptable**.
+
+Instead the
+
+```text
+HTTP/1.1 404 Not Found
+...
+```
+
+should be returned.
+
+## Recommended Reading
+
+* [How to Think About HTTP Status Codes](https://www.mnot.net/blog/2017/05/11/status_codes)
+