Merge branch 'master' into naming-conventions

rest-api-guidelines/application/README.md

@@ -2,5 +2,5 @@
 
 Every API **SHOULD** use company terms for resource names, relation names and representation message field names.
 
-Also, every API **MUST** follow the [naming conventions](../../quality/evolution/naming-conventions.md).
+Also, every API **MUST** follow the [naming conventions](../evolution/naming-conventions.md).
 

rest-api-guidelines/core-principles/apiary.md

@@ -1,12 +0,0 @@
-# API Design Platform
-
-1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](../../general-guidelines/api-first.md). Apiary **MUST** be used during API Design.
-2. Every API description **MUST** be stored in [Apiary](https://apiary.io/) under the ADIDAS team.
-3. Apiary **MUST** be the **single source of truth** to learn about existing APIs within the organization.
-
-> NOTE: Apiary supports API-first approach in multiple ways:  
-> a. Validates API description for correctness and automatically generates API documentation to drive the discussion between stakeholders. \(No more emails with API description flying between stakeholders\)
->
-> NOTE: The synchronization between the version control system and adidas [API Description platform](apiary.md)  
-> should be automated using CI/CD framework.
-

rest-api-guidelines/core-principles/design-platform.md

@@ -0,0 +1,12 @@
+# API Design Platform
+
+1. [SwaggerHub](https://swagger.io/tools/swaggerhub/) is the primary platform supporting [API first approach](../../general-guidelines/api-first.md). SwaggerHub **SHOULD** be used during API Design.
+2. Every API description **MUST** be stored in [SwaggerHub](https://design.api.3stripes.io/) under the adidas team.
+3. SwaggerHub **MUST** be the **single source of truth** to learn about existing APIs within the organization.
+
+> NOTE: SwaggerHub supports API-first approach in multiple ways:  
+> For example, it validates API description for correctness and automatically generates API documentation to drive the discussion between stakeholders. \(No more emails with API description flying between stakeholders\)
+>
+> NOTE: The synchronization between the version control system and adidas API Design platform 
+> should be automated (e.g. using CI/CD framework or the Design Platform capabilities).
+

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

@@ -2,7 +2,7 @@
 
 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).
 
-Every API description **MUST** be published in adidas [API design platform](apiary.md) and it **SHOULD** be stored in version control system \(Bitbucket, GitHub\) in the same repository as the API implementation.
+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
 

rest-api-guidelines/core-principles/testing.md

@@ -1,6 +1,18 @@
 # Testing
 
-Every API description \(contract\) using HTTP\(S\) protocol **MUST** be tested against its API implementation. The tests **MUST** be executed using the [Dredd testing framework](https://github.com/apiaryio/dredd). The Dredd **MUST** [report the test results to Apiary](https://help.apiary.io/tools/automated-testing/testing-reporter/).
+## DREDD
+
+Every API description \(contract\) using HTTP\(S\) protocol **MUST** be tested against its API implementation. The tests **MUST** be executed using the [Dredd testing framework](https://github.com/apiaryio/dredd).
 
 In addition to local runs, the tests **SHOULD** be an integral part the API implementation's CI/CD pipeline. The CI/CD pipeline **SHOULD** be configured to run the test whenever there is a change to either API description \(contract\) or its implementation.
 
+## PACT
+
+Every adidas **CORE** API **MUST** be tested additionally applying Consumer Driven Contract Testing principles. The tests **MUST** be executed using the [PACT contract testing tool](https://docs.pact.io/). PACT tests **MUST** use adidas [PACT-Broker](http://pact.ati.adidas.com/) to store results and evidences.
+
+In addition to local runs, PACT tests **SHOULD** be an integral part of the API implementation's CI/CD pipeline. The CI/CD pipeline **SHOULD** be configured to run the test whenever there is a change to either API description \(contract\) or its implementation.
+
+Using Consumer Driven Contract Testing with PACT is *not mandatory* for adidas **NON-CORE** APIs, but strongly recommended due to the advantages this approach brings. It will be also a proof of our Software Engineering practices maturity.
+
+More information, guides and seeds about how to use PACT can be found on (internal link)[adidas Consumer Driven Contract Testing guide](https://tools.adidas-group.com/confluence/display/DSBP/adidas+Consumer+Driven+Contract+Testing+guide) page.
+

rest-api-guidelines/evolution/reserved-identifiers.md

@@ -4,8 +4,8 @@ The list of all reserved identifiers or identifiers with special meaning.
 
 ## Representation Format Fields
 
-* `_links` - [HAL](../../functionality/message/hal.md)
-* `_embedded` - [HAL](../../functionality/message/hal.md)
+* `_links` - [HAL](../message/hal.md)
+* `_embedded` - [HAL](../message/hal.md)
 
 ## Query Parameters
 

rest-api-guidelines/evolution/versioning.md

@@ -13,7 +13,7 @@ Any change to:
 4. **Relation** with other resources \(e.g Links\)  
 5. **Representation format** \(e.g. HTTP request and response bodies\)
 
-**MUST** follow the [**Rules for Extending**](../../../general-guidelines/rules-for-extending.md).
+**MUST** follow the [**Rules for Extending**](../../general-guidelines/rules-for-extending.md).
 
 ## Identifier Stability \(No URI Versioning\)
 
@@ -29,7 +29,7 @@ Adding a new action to existing resource with identifier `/greeting` doesn't cha
 
 ## Backward-incompatible Changes
 
-A change to _resource identifier_, _resource metadata_, _resource actions_ and _resource relations_ that can't follow the [Rules for Extending](../../../general-guidelines/rules-for-extending.md) **MUST** result into a **new resource variant**. Existing resource variant **MUST** be preserved.
+A change to _resource identifier_, _resource metadata_, _resource actions_ and _resource relations_ that can't follow the [Rules for Extending](../../general-guidelines/rules-for-extending.md) **MUST** result into a **new resource variant**. Existing resource variant **MUST** be preserved.
 
 A change to _representation format_ **SHOULD NOT** result into a new resource variant.
 
@@ -41,7 +41,7 @@ Currently, optional URI Query Parameter `first` on an existing resource `/greeti
 
 > A representation format is the serialization format \(media type\) used in request and response bodies, and typically it represents a resource or its part, possibly with additional hypermedia controls.
 
-If a change can't follow the Rules for Extending the representation format media type **MUST** be changed. If the media type has been changed the previous media type, **MUST** be available via [Content Negotiation](../../functionality/message/content-negotiation.md).
+If a change can't follow the Rules for Extending the representation format media type **MUST** be changed. If the media type has been changed the previous media type, **MUST** be available via [Content Negotiation](../message/content-negotiation.md).
 
 If the media type conveys the version parameter, the version parameter **SHOULD** follow [Semantic versioning](http://semver.org/).
 
@@ -87,13 +87,6 @@ info:
 
 Has MAJOR version 2, MINOR version 1 and PATCH version 3.
 
-#### Demo
-
-API description \(OAS2\) files demonstrating a proposal of an backward-incompatible change turned into a backward compatible change are available at [Bitbucket \(diff\) ](https://bitbucket.org/apidesigner/demo-versioning-api/pull-requests/1/add-name-parameter/diff)and documented in Apiary:
-
-* [Production version](https://demoversioningproduction.docs.apiary.io/#) as being consumed by clients
-* [Development version](https://demoversioningdevelopment.docs.apiary.io/#) proposing a backward incompatible change
-
 #### Recommended Reading
 
 * [Evolving HTTP APIs](https://www.mnot.net/blog/2012/12/04/api-evolution)

rest-api-guidelines/execution/asynchronous-tasks.md

@@ -0,0 +1,105 @@
+# Asynchronous Tasks
+
+If an API operation is asynchronous, but a client could track its progress, the response to such an asynchronous operation **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.
+
+## Task Tracking Resource
+
+The task-tracking resource **SHOULD** convey the information about the status of an asynchronous task.
+
+Retrieval of such a resource using the HTTP GET Request Method **SHOULD** be designed as follows:
+
+1. Task is Still Processing
+
+   Return **200 OK** and representation of the current status.
+
+2. Task Successfully Completed
+
+   Return **303 See Other** together with [HTTP Location Header](https://tools.ietf.org/html/rfc7231#section-7.1.2) with URI or a outcome resource.
+
+3. Task Failed
+
+   Return **200 OK** and `application/problem+json` with the problem detail information on the task has failed.
+
+## Design Note
+
+The asynchronous operation task-tracking resource can be either **polled** by client or the client might initially provide a **callback** to be executed when the operation finishes.
+
+In the case of callback, the API and its client MUST agree on what HTTP method and request format is used for the callback invitation. If built within adidas, the "client" API is also the subject of the adidas API guidelines.
+
+### Example
+
+1. **Initiate the asynchronous task**
+  
+    ```
+    POST /feeds/tasks/ HTTP/1.1
+    Content-Type: application/json
+    ...
+
+    HTTP/1.1 202 Accepted
+    Content-Type: application/hal+json
+    Retry-After: 60
+
+    {
+      "_links": {
+        "self": { "href": "/feeds/tasks/1" }
+      },
+      "message": "Your task to generate feed has been accepted. Try query for result after 60 seconds.",
+      "retryAfter": 60
+    }
+    ```
+
+1. **Poll the task status: In progress**
+
+    ```
+    GET /feeds/tasks/1 HTTP/1.1
+    ...
+
+    HTTP/1.1 200 Ok
+    Content-Type: application/hal+json
+    Retry-After: 30
+
+    {
+      "_links": {
+        "self": { "href": "/feeds/tasks/1" }
+      },
+      "message": "Your feed is being generated. Try query for result after 30 seconds.",
+      "retryAfter": 30
+    }
+    ```
+
+1. **Poll the task status: Finished**
+
+    ```
+    GET /feeds/tasks/1 HTTP/1.1
+    ...
+
+    HTTP/1.1 303 See Other
+    Location: /feeds/1
+    Content-Location: /feeds/tasks/1
+    Content-Type: application/hal+json
+
+    {
+      "_links": {
+        "self": { "href": "/feeds/tasks/1" },
+        "feed": { "href": "/feeds/1" }
+      },
+      "message": "Your feed is ready."
+    }
+    ```
+
+1. **Poll the task status: Failure**
+
+    ```
+    GET /feeds/tasks/1 HTTP/1.1
+    ...
+
+    HTTP/1.1 200 OK
+    Content-Type: application/problem+json
+
+    {
+      "title": "Wrong input parameters",
+      "detail: "Missing required input parameter XYZ.",
+      "status": 400
+    }
+    ```
+

rest-api-guidelines/execution/batch-operations.md

@@ -70,7 +70,7 @@ However, in such an operation has to be provided such a non-atomic bulk operatio
 
 1. Non-atomic bulk operation **MUST** return a success status code \(e.g. **200 OK**\) only if every and all sub-operation succeeded.
 2. If any single one sub-operation fails the whole non-atomic bulk operation **MUST** return the respective **4xx** or **5xx** status code.
-3. In the case of a failure the response **MUST** contain the [problem detail](../../functionality/message/message-formats.md#error-response-format) information about every sub-operation that has failed.
+3. In the case of a failure the response **MUST** contain the [problem detail](../message/message-formats.md#error-response-format) information about every sub-operation that has failed.
 4. **The client MUST be aware that the operation is non-atomic and the even the operation might have failed some sub-operations were processed successfully.**
 
 ### Example

rest-api-guidelines/execution/pagination.md

@@ -15,7 +15,7 @@ The Collection of Orders using the collection navigation link and `offset` and `
     "first": { "href": "/orders?limit=10" },
     "last": { "href": "/orders?offset=900&limit=10" }
   },
-  "total_count": 910,
+  "totalCount": 910,
   "_embedded": {
     "order": [
       { ... },

rest-api-guidelines/functionality/README.md

@@ -1,4 +0,0 @@
-# Functionality
-
-
-

rest-api-guidelines/functionality/message/HAL-snippet-full-OpenApi3.yaml

@@ -0,0 +1,81 @@
+openapi: 3.0.0
+info:
+  title: HAL
+  description: 'HAL snippet for OAS3'
+  contact:
+    name: Andrzej Jarzyna
+    url: https://github.com/jerzyn
+    email: andrzej.jarzyna@adidas.com
+  version: '1.0.0'
+servers:
+- url: http://{defaultHost}
+  variables:
+    defaultHost:
+      default: www.example.com
+paths: {}
+components:
+  schemas:
+    HALLinkObject:
+      title: HALLinkObject
+      required:
+      - href
+      type: object
+      properties:
+        href:
+          type: string
+        templated:
+          type: boolean
+        type:
+          type: string
+        deprecation:
+          type: string
+        name:
+          type: string
+        profile:
+          type: string
+        title:
+          type: string
+        hreflang:
+          type: string
+    HALCuriesLink:
+      title: HALCuriesLink
+      required:
+      - templated
+      - href
+      type: object
+      properties:
+        templated:
+          type: string
+          example: True
+        href:
+          type: string
+        type:
+          type: string
+        deprecation:
+          type: string
+        name:
+          type: string
+        profile:
+          type: string
+        title:
+          type: string
+        hreflang:
+          type: string
+    HAL:
+      title: HAL
+      type: object
+      properties:
+        _links:
+          $ref: '#/components/schemas/Links'
+        _embedded:
+          type: object
+          additionalProperties:
+            $ref: '#/components/schemas/HAL'
+      description: JSON Hypertext Application Language. Definition of [HAL message format](https://tools.ietf.org/html/draft-kelly-json-hal-08)
+    Links:
+      title: Links
+      type: object
+      properties:
+        curies:
+          $ref: '#/components/schemas/HALCuriesLink'
+tags: []

rest-api-guidelines/functionality/message/HAL-snippet.yaml

@@ -0,0 +1,74 @@
+swagger: "2.0"
+info:
+  title: HAL
+  description: HAL snippet for OAS2
+  version: 1.0.0
+host: api.example.com
+basePath: /v1
+schemes:
+  - https
+paths: {}
+definitions: 
+  HalLinkObject:
+    title: HAL Link Object
+    type: object
+    properties:
+      href:
+        type: string
+      templated:
+        type: boolean
+      type:
+        type: string
+      deprecation:
+        type: string
+      name:
+        type: string
+      profile:
+        type: string
+      title:
+        type: string
+      hreflang:
+        type: string
+    required:
+      - href
+  HalCuriesLink:
+    title: HAL Curies Link
+    allOf:
+      - type: object
+        properties:
+          templated:
+            enum:
+              - true
+        required:
+          - templated
+      - $ref: '#/definitions/HalLinkObject'
+  HAL:
+    title: HAL
+    description: >-
+      JSON Hypertext Application Language. Definition of [HAL message
+      format](https://tools.ietf.org/html/draft-kelly-json-hal-08)
+    type: object
+    properties:
+      _links:
+        type: object
+        additionalProperties:
+          allOf:
+            - $ref: '#/definitions/HalLinkObject'
+            - type: array
+              items:
+                $ref: '#/definitions/HalLinkObject'
+        properties:
+          curies:
+            allOf:
+              - $ref: '#/definitions/HalCuriesLink'
+              - type: array
+                items:
+                  $ref: '#/definitions/HalCuriesLink'
+      _embedded:
+        type: object
+        additionalProperties:
+          allOf:
+            - $ref: '#/definitions/HAL'
+            - type: array
+              items:
+                $ref: '#/definitions/HAL'

rest-api-guidelines/guides/README.md

@@ -1,11 +1,9 @@
 # Guides
 
-API-related guides:
+## API-related guides
 
 * [API Design Process](https://tools.adidas-group.com/confluence/display/EA/API+Design+Process)
 * Migration of Legacy Services \(SOAP\)
 * API Testing with Dredd
 * Continuous Integration / Deployment / Delivery
-* [Apiary](https://help.apiary.io/api_101/understanding-apiary/)
 * API Management
-

rest-api-guidelines/guides/api-testing-ci-environment.md

@@ -10,14 +10,7 @@ The following must be available in the CI environment before testing:
 
    ```text
     $ node -v
-    v7.5.0
-   ```
-
-2. **Ruby** runtime MUST be available in the CI environment:
-
-   ```text
-    $ ruby -v
-    ruby 2.4.0p0 (2016-12-24 revision 57164) [x86_64-darwin16]
+    v12.16.0
    ```
 
 3. [**Dredd**](https://github.com/apiaryio/dredd) MUST be installed globally in the CI environment:
@@ -28,55 +21,22 @@ The following must be available in the CI environment before testing:
 
    ```text
     $ dredd --version
-    dredd v2.2.5 (Darwin 16.4.0; x64)
+    dredd v13.0.1
    ```
 
-4. [**Apiary CLI Tool**](https://help.apiary.io/tools/apiary-cli) MUST be installed globally in the CI environment:
-
-   ```text
-    $ gem install apiaryio
-   ```
-
-   ```text
-    $ apiary version
-    0.8.0
-   ```
-
-5. **Apiary API Key** MUST be set in the CI Environment environment variables:
-
-   ```text
-    $ export APIARY_API_KEY=xyz
-   ```
-
-   To obtain an Apiary API key, head to [https://login.apiary.io/tokens](https://login.apiary.io/tokens) \(NOTE: You will need the "ALL" Scope\)
-
 ## Testing an API
 
 ### Test Run Prerequisites
 
 To test an API within the CI environment provisioned as mentioned in the environment prerequisites, you will need the following:
 
-1. The name \(subdomain\) of API project at Apiary
+1. A `swagger.yaml` file with the description of API being tested
 
-   ```text
-    $ export APIARY_API_NAME=bomapi3
-   ```
+   The OpenAPI Specifciation file should be fetched from [API Design Platform](design-plaform.md). In the case of SwaggerHub API Design Platform, the file can be fetched manually or via their API. Refer to [Integrating with the SwaggerHub API](https://swagger.io/blog/api-development/integrating-with-the-swaggerhub-api/), for details how to use SwaggerHub API.
 
-   > See [How to find the Apiary API name](https://help.apiary.io/faq/find-api-name/) for more details.
+   Alternativelly this can also be a remote file e.g. SwaggerHub URL, if the API is public its OAS file and reachable from the testing host.
 
-2. A `swagger.yaml` file with the description of API being tested
-
-   To fetch the swagger.yaml file from Apiary run the following command before the test:
-
-   ```text
-    $ apiary fetch --api-name=$APIARY_API_NAME --output="swagger.yaml"
-   ```
-
-   The swagger document for Apiary project `bomapi3` was saved as local file `./swagger.yaml`.
-
-   > See [Fetching Published Documentation](https://help.apiary.io/tools/apiary-cli/#fetching-published-documentation).
-
-3. The host \(address\) of the service being tested
+2. The host \(address\) of the service being tested
 
    ```text
      $ export API_HOST=http://deheremap7336.emea.adsint.biz:8004`
@@ -84,10 +44,10 @@ To test an API within the CI environment provisioned as mentioned in the environ
 
 ### Running the Test
 
-With all of the above \(`APIARY_API_KEY`, `APIARY_API_NAME`, `API_HOST`, set up and `swagger.yaml` file present in the current directory\), run:
+Run:
 
 ```text
-$ dredd swagger.yaml $API_HOST -r apiary
+$ dredd swagger.yaml $API_HOST
 ```
 
 > See [Dredd Command-line Interface](https://dredd.readthedocs.io/en/latest/usage-cli/).
@@ -98,5 +58,4 @@ The Dredd will perform the tests and exits usually if the tests have passed. You
 $ echo $?
 ```
 
-Everything else but `0` should break the build. The test results will be visible in the CLI \(log\) as well as in Apiary.
-
+Everything else but `0` should break the build. The test results will be visible in the CLI \(log\)

rest-api-guidelines/guides/complete-api-development.md

@@ -1,5 +1,7 @@
 # Complete API Development
 
+> NOTE: The content of this file is outdated, refering to previous technologies used at adidas. It is kept for reference until its refresh
+
 1. **Design the API**
    1. Analyze business requirements
    2. Identify affordances

rest-api-guidelines/message/error-reporting.md

@@ -4,7 +4,7 @@ The [`application/problem+json`](https://tools.ietf.org/html/rfc7807) \(Problem
 
 Problem Detail is intended for use with the HTTP status codes 4xx and 5xx. Problem Detail **MUST NOT** be used with 2xx status code responses.
 
-At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields.
+At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. `title` value **SHOULD NOT** change from occurrence to occurence of the problem, except for purposes of localization (e.g., using proactive content negotiation) [read more](https://tools.ietf.org/html/rfc7807#section-3.1)
 
 ### Example
 
@@ -15,6 +15,8 @@ At the minimum, any Problem Detail response **MUST** have the `title` and `detai
 }
 ```
 
+> NOTE: `title` and `detail` fields **SHOULD NOT** be parsed to determine the nature of the error. Instead `type` **MUST** be used.
+
 ## Optional Fields
 
 It **SHOULD** has the `type` field with the identifier of the error, besides it **MAY** have the `instance` field with the URI of the resource in question. If the Problem Detail response has the `status` field it **MUST** have the same value as HTTP Status code from of the response.
@@ -39,7 +41,7 @@ If needed, the Problem Detail **MAY** include additional fields, refer to [RFC78
 
 When necessary, a Problem Detail response **MAY** include additional error details about the problems that have occurred.
 
-These additional errors **MUST** be under the `errors` and **MUST** follow the Problem Detail structure.
+These additional errors **MUST** be under the `errors` collection and **MUST** follow the Problem Detail structure.
 
 ### Example
 
@@ -122,5 +124,8 @@ A Problem Detail response **MUST NOT** contain a program stack trace or server l
 
 ## Working with Problem Detail
 
-There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\).
+An API description **MAY** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code.
 
+## External resources
+
+There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\).

rest-api-guidelines/message/hal.md

@@ -8,6 +8,12 @@ The [`application/hal+json`](http://stateless.co/hal_specification.html) \(HAL\)
 
 This document is an informal introduction to the HAL media type. For more details see [HAL - Hypertext Application Language Specification](http://stateless.co/hal_specification.html).
 
+## HAL Document Object Model
+
+HAL document follow the object model defined in JSON-schema [here](https://supermodel.io/adidas/api/HAL).
+
+YAML code snippets are provided for [OpenAPI Specification 2.0/Swagger](https://github.com/adidas/api-guidelines/tree/4a033eb0cf8ec582102c09c1eb5ba1fa8a5597d9/rest-api-guidelines/functionality/message/HAL-snippet.yaml) and [OpenAPI Specification 3.x](https://github.com/adidas/api-guidelines/tree/4a033eb0cf8ec582102c09c1eb5ba1fa8a5597d9/rest-api-guidelines/functionality/message/HAL-snippet-full-OpenApi3.yaml).
+
 ## Simple Document Example
 
 The simplest Hal document looks like an empty JSON \(it is an empty JSON!\):
@@ -113,6 +119,8 @@ Some APIs using HAL:
 
 Refer to the [extensive list of libraries that work with HAL](https://github.com/mikekelly/hal_specification/wiki/Libraries).
 
+For working with HAL and Node.js using [HALson npm package](https://www.npmjs.com/package/halson) is suggested.
+
 ### Spring Framework
 
 Spring framework supports HAL out of the box. More info can be found in [Spring Documentation](https://spring.io/guides/gs/rest-hateoas/) and [examples](https://github.com/spring-guides/gs-rest-hateoas).

rest-api-guidelines/miscellaneous.md

@@ -2,4 +2,9 @@
 
 * [Product tokens](https://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-16#section-6.3)
 * [Deprecating "X-"](https://tools.ietf.org/html/rfc6648)
+* [Collection of standards and specifications for HTTP/REST APIs](http://standards.rest)
+* [Official list of HTTP Message Headers](https://www.iana.org/assignments/message-headers/message-headers.xhtml)
 
+## Tools documentation
+
+* [SwaggerHub Documentation](https://app.swaggerhub.com/help/index)

rest-api-guidelines/protocol/http.md

@@ -10,7 +10,7 @@ Once you are familiar with the **HTTP message structure** learn about the **HTTP
 
 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.
+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
 

rest-api-guidelines/quality/README.md

@@ -1,4 +0,0 @@
-# Quality
-
-
-

rest-api-guidelines/quality/execution/asynchronous-tasks.md

@@ -1,28 +0,0 @@
-# Asynchronous Tasks
-
-If an API operation is asynchronous, but a client could track its progress, the response to such an asynchronous operation **MUST** return, in the case of success, the **202 Accepted** status code together with an `application/hal+json` representation of a new **task-tracking resource**.
-
-## Task Tracking Resource
-
-The task-tracking resource **SHOULD** convey the information about the status of an asynchronous task.
-
-Retrieval of such a resource using the HTTP GET Request Method **SHOULD** be designed as follows:
-
-1. Task is Still Processing
-
-   Return **200 OK** and representation of the current status.
-
-2. Task Successfully Completed
-
-   Return **303 See Other** together with [HTTP Location Header](https://tools.ietf.org/html/rfc7231#section-7.1.2) with URI or a outcome resource.
-
-3. Task Failed
-
-   Return **200 OK** and `application/problem+json` with the problem detail information on the task has failed.
-
-## Design Note
-
-The asynchronous operation task-tracking resource can be either **polled** by client or the client might initially provide a **callback** to be executed when the operation finishes.
-
-In the case of callback, the API and its client MUST agree on what HTTP method and request format is used for the callback invitation. If built within adidas, the "client" API is also the subject of the adidas API guidelines.
-

rest-api-guidelines/rest.md

@@ -2,7 +2,7 @@
 
 ## adidas REST API Guidelines
 
-The adidas REST API Guidelines defines standards and guidelines for building REST APIs at adidas. **These Guidelines has to be followed in addition to the adidas** [**General API Guidelines.**](../general-guidelines/general-guidelines.md)
+Adidas REST API Guidelines define standards and guidelines for building REST APIs at adidas. **These Guidelines have to be followed in addition to the Adidas** [**General API Guidelines.**](../general-guidelines/general-guidelines.md)
 
 The REST API Guidelines are further split into the following parts:
 
@@ -11,26 +11,26 @@ The REST API Guidelines are further split into the following parts:
   REST API Guidelines Core Principles defines the rules that **MUST** be followed at throughout the full API lifecycle.
 
 * **Functionality Guidelines**
-  * \*\*\*\*[**Protocol level**](functionality/protocol/)\*\*\*\*
+  * \*\*\*\*[**Protocol level**](protocol/)\*\*\*\*
 
     Protocol guidelines define the protocols used within the organization.
 
-  * \*\*\*\*[**Message level**](functionality/message/)\*\*\*\*
+  * \*\*\*\*[**Message level**](message/)\*\*\*\*
 
     The Message guidelines define the structure and semantics of messages used to exchange information.
 
-  * \*\*\*\*[**Application level**](functionality/application/)
+  * \*\*\*\*[**Application level**](application/)
 
     The Application guidelines define the definition and use of application-specific semantics.
 * **Quality Guidelines**
 
   Evolution and Execution guidelines define the rules for achieving the desired architectural qualities of systems.
 
-  * \*\*\*\*[**Evolution**](quality/evolution/)\*\*\*\*
+  * \*\*\*\*[**Evolution**](evolution/)\*\*\*\*
 
     Evolution qualities governance, such as testability, maintainability, extensibility, and scalability.
 
-  * \*\*\*\*[**Execution**](quality/execution/)\*\*\*\*
+  * \*\*\*\*[**Execution**](execution/)\*\*\*\*
 
     Execution qualities governance, such as security and usability.