From 4526f3d8a30f6503637f469f9796cbfccd40d96e Mon Sep 17 00:00:00 2001 From: apidesigner Date: Tue, 14 Feb 2017 14:46:41 +0000 Subject: [PATCH] Updates protocol/separate-concerns.md Auto commit by GitBook Editor --- protocol/http.md | 2 +- protocol/know-your-http.md | 2 +- protocol/separate-concerns.md | 22 +++++++++++----------- protocol/tls.md | 4 ++-- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/protocol/http.md b/protocol/http.md index a9dc1ea..d7d260b 100644 --- a/protocol/http.md +++ b/protocol/http.md @@ -1,5 +1,5 @@ # HTTP -Every API MUST support [HTTP/1.1](https://tools.ietf.org/html/rfc7230) and MUST adhere to its semantic. +Every API MUST support [HTTP/1.1](https://tools.ietf.org/html/rfc7230) and **MUST** adhere to its **semantic**. diff --git a/protocol/know-your-http.md b/protocol/know-your-http.md index 98ee7a7..b5c6fb2 100644 --- a/protocol/know-your-http.md +++ b/protocol/know-your-http.md @@ -1,5 +1,5 @@ # Know your HTTP -Every API using HTTP MUST conform to the HTTP protocol semantics as defined in the following RFCs: +Every API using HTTP **MUST** conform to the HTTP protocol semantics as defined in the following RFCs: > 1. [RFC 7230, HTTP/1.1: Message Syntax and Routing](https://tools.ietf.org/html/rfc7230) > 1. [RFC 7231, HTTP/1.1: Semantics and Content](https://tools.ietf.org/html/rfc7231) diff --git a/protocol/separate-concerns.md b/protocol/separate-concerns.md index d509f62..cd951ef 100644 --- a/protocol/separate-concerns.md +++ b/protocol/separate-concerns.md @@ -1,20 +1,20 @@ # Separate Concerns -Every API using HTTP/S API MUST clearly follow the concern separation of a HTTP message: +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 +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 #### Example 1 The rule -> A resource identifier–URI MUST be used to indicate identity only +> 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. +implies there **MUST NOT** be an 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 @@ -22,7 +22,7 @@ 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: +implies an HTTP GET request **MUST NOT** use HTTP message body to identify the resource. For example a request: ``` GET /greeting HTTP/1.1 @@ -36,7 +36,7 @@ Content-Type: application/json } ``` -is **illegal** (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`. +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`. --- diff --git a/protocol/tls.md b/protocol/tls.md index 4d59eac..2346049 100644 --- a/protocol/tls.md +++ b/protocol/tls.md @@ -1,4 +1,4 @@ # Transport Layer Security (TLS) -Every API MUST require secure connections with TLS. That is, an API using the HTTP protocol MUST use **HTTPS**. +Every API **MUST** require secure connections with TLS. 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. \ No newline at end of file +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. \ No newline at end of file