Merge pull request #78 from ianschechtman/master

Fix/improve readability

rest-api-guidelines/core-principles/openapi-specification.md

@@ -1,10 +1,10 @@
 # OpenAPI Specification
 
-Every API **MUST** be described using an API description format. The API description format used MUST be the [OpenAPI Specification \(formerly known as Swagger Specification\) version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) OR the[OpenAPI Specification \(formerly known as Swagger Specification\) version 3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md).
+Every API **MUST** be described using an API description format. The API description format used **MUST** be the [OpenAPI Specification \(formerly known as Swagger Specification\) version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) OR the [OpenAPI Specification \(formerly known as Swagger Specification\) version 3.0.x](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md).
 
 Every API description **MUST** be published in adidas [API design platform](design-platform.md) and it **SHOULD** be stored in version control system \(Bitbucket, GitHub\) in the same repository as the API implementation.
 
 ## Language
 
-The API description MUST be written in **American English**.
+The API description **MUST** be written in **American English**.
 

rest-api-guidelines/message/content-negotiation.md

@@ -22,9 +22,9 @@ 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 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.
+> 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).
 

rest-api-guidelines/message/foreign-key-relations.md

@@ -2,7 +2,7 @@
 
 ## Link or Embed Foreign Key Relation
 
-When a resource representation includes relation with another \(foreign\) resource, the relation **MUST** be expressed as a link relation or embed the related resource.
+When a resource representation includes a relation with another \(foreign\) resource, the relation **MUST** be expressed as a link relation or embed the related resource.
 
 ### Example
 
@@ -33,7 +33,7 @@ or:
 }
 ```
 
-instead:
+instead of:
 
 ```javascript
 {
@@ -60,7 +60,7 @@ Use:
 }
 ```
 
-instead:
+instead of:
 
 ```javascript
 {
@@ -68,5 +68,5 @@ instead:
 }
 ```
 
-> NOTE: As a rule of thumb, in an HTTP message body, there SHOULD NOT be any field with trailing "\_id," "\_href," "\_url" etc. in its name.
+> NOTE: As a rule of thumb, in an HTTP message body, there **SHOULD NOT** be any field with trailing "\_id," "\_href," "\_url" etc. in its name.
 

rest-api-guidelines/message/hal.md

@@ -12,7 +12,7 @@ This document is an informal introduction to the HAL media type. For more detail
 
 ## HAL Document Object Model
 
-HAL document follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL). 
+HAL documents follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL). 
 
 IANA created a list explaining the standard relationships for REST. Do not forget to have a look [here](http://www.iana.org/assignments/link-relations/link-relations.xhtml) to find the role of each type of relation. 
 
@@ -48,7 +48,7 @@ In our case the "Greeting" resource isn't related to other resources but itself,
 
 > NOTE: It is **customary** for every resource representation to include the `self` link relation.
 >
-> NOTE: The href **MUST** always be **relative path to the API root** \(e.g. without the host and scheme\).
+> NOTE: The href **MUST** always be the **relative path to the API root** \(e.g. without the host and scheme\).
 
 ## Relation Example
 
@@ -72,7 +72,7 @@ A more complex document example could be an "Order" resource that has a related
 
 ## Embedding Example
 
-Let's assume there is an "Orders" resource which is a collection of all orders from different authors. There is the relation between the Orders resource and possibly many Order resources.
+Let's assume there is an "Orders" resource which is a collection of all orders from different authors. There is a relation between this Orders resource and possibly many other Orders resources.
 
 We could express this in the `_links` object using the `order` relation, but sometimes it is practical to "embed" \(entirely or partially\) related resources representations in the originating resource representation. For a scenario like this HAL offers the `_embedded` field.
 

rest-api-guidelines/message/message-formats.md

@@ -10,7 +10,7 @@ The [`application/problem+json`](https://tools.ietf.org/html/rfc7807) \(Problem
 
 ## Request Message Format
 
-**Request** messages with body **SHOULD** support a [`application/json`](http://www.json.org) \(JSON\) format. Where applicable, request message **SHOULD** also support the [`application/hal+json`](http://stateless.co/hal_specification.html) format.
+**Request** messages with body **SHOULD** support an [`application/json`](http://www.json.org) \(JSON\) format. Where applicable, the request message **SHOULD** also support the [`application/hal+json`](http://stateless.co/hal_specification.html) format.
 
 **Request** messages **MAY** also support the [`application/x-www-form-urlencoded`](https://tools.ietf.org/html/rfc1866#section-8.2.1) \(URL Encoded\) format.
 

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

@@ -1,6 +1,6 @@
 # Separate Concerns
 
-Every API using HTTP/S API **MUST** precisely follow the concern separation of an HTTP message:
+Every API using HTTP/S **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\)

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

@@ -10,7 +10,7 @@ At a minimum everyone **MUST** be familiar with the semantics of ["Common" HTTP
 
 ## Use Codes 4xx or 5xx to Communicate Errors
 
-Remember the 4xx range concern to errors in the API Consumer/Client side while 5xx range concerns to the upstream/backend service, the API implementation.
+The 4xx range concerns errors in the API Consumer/Client side, while 5xx range concerns errors in the upstream/backend service or the API implementation.
 
 A request:
 
@@ -19,7 +19,7 @@ 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:
+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
@@ -35,7 +35,7 @@ Content-Type: application/json
 
 is **not acceptable**.
 
-Instead the
+Instead
 
 ```text
 HTTP/1.1 404 Not Found