diff --git a/rest-api-guidelines/core-principles/openapi-specification.md b/rest-api-guidelines/core-principles/openapi-specification.md index 015cd9f..fe7c56d 100644 --- a/rest-api-guidelines/core-principles/openapi-specification.md +++ b/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**. diff --git a/rest-api-guidelines/message/content-negotiation.md b/rest-api-guidelines/message/content-negotiation.md index 4105483..96f9a39 100644 --- a/rest-api-guidelines/message/content-negotiation.md +++ b/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). diff --git a/rest-api-guidelines/message/foreign-key-relations.md b/rest-api-guidelines/message/foreign-key-relations.md index 156745b..b0f9b28 100644 --- a/rest-api-guidelines/message/foreign-key-relations.md +++ b/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. diff --git a/rest-api-guidelines/message/hal.md b/rest-api-guidelines/message/hal.md index 310328c..66594fa 100644 --- a/rest-api-guidelines/message/hal.md +++ b/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. diff --git a/rest-api-guidelines/message/message-formats.md b/rest-api-guidelines/message/message-formats.md index fe4ac2e..ec41bb2 100644 --- a/rest-api-guidelines/message/message-formats.md +++ b/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. diff --git a/rest-api-guidelines/protocol/separate-concerns.md b/rest-api-guidelines/protocol/separate-concerns.md index 96ca258..7fe7c2f 100644 --- a/rest-api-guidelines/protocol/separate-concerns.md +++ b/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\) diff --git a/rest-api-guidelines/protocol/use-appropriate-status-codes.md b/rest-api-guidelines/protocol/use-appropriate-status-codes.md index 823f5b3..a6323b3 100644 --- a/rest-api-guidelines/protocol/use-appropriate-status-codes.md +++ b/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