Creates rest/core-principles/quality.md

Auto commit by GitBook Editor

rest/core-principles/README.md

@@ -0,0 +1,2 @@
+# Core Principles
+This section outlines the foundation upon which the API Guidelines are built. 

rest/core-principles/apiary.md

@@ -0,0 +1,16 @@
+# API Design Platform - Apiary
+
+1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](./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 GROUP 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/core-principles/design-maturity.md

@@ -0,0 +1,16 @@
+# Design & Implementation Maturity
+
+## API Design Maturity
+> How to design an API
+
+
+Every API design **MUST** be **resource-centric** ([Web API Design Maturity Model Level 2](http://amundsen.com/talks/2016-11-apistrat-wadm/2016-11-apistrat-wadm.pdf)). That is an API design **MUST** revolve around Web-styled _resources_, _relations_ between the resources and the _actions_ the resources may afford. 
+
+An API design **MAY** be **affordance-centric** ([Web API Design Maturity Model Level 3](http://amundsen.com/talks/2016-11-apistrat-wadm/2016-11-apistrat-wadm.pdf)).
+
+## API Design Implementation Maturity
+> How to implement the API design
+
+Every API design implementation using the HTTP protocol **MUST** use the appropriate **HTTP Request Method** ([Richardson Maturity Model Level 2](https://martinfowler.com/articles/richardsonMaturityModel.html#level2)) to implement an action afforded by a resource.
+
+An API design implementation **SHOULD** include **hypermedia controls** (HATEOAS) ([Richardson Maturity Model Level 3](https://martinfowler.com/articles/richardsonMaturityModel.html#level3)).

rest/core-principles/introduction.md

@@ -0,0 +1,45 @@
+# 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 General Guidelines.
+
+The REST API Guidelines are further split into the following parts:
+
+* **Core Principles**
+
+  REST API Guidelines Core Principles defines the rules that **MUST** be followed at throughout the full API lifecycle.
+
+* **Functionality Guidelines**
+
+  * [**Protocol level**](https://adidas-group.gitbooks.io/api-guidelines/content/protocol/)
+
+    Protocol guidelines define the protocols used within the organization.
+
+  * [**Message level**](https://adidas-group.gitbooks.io/api-guidelines/content/message/)
+
+    The Message guidelines define the structure and semantics of messages used to exchange information.
+
+  * [**Application level**](https://adidas-group.gitbooks.io/api-guidelines/content/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**](https://adidas-group.gitbooks.io/api-guidelines/content/evolution/)
+
+    Evolution qualities governance, such as testability, maintainability, extensibility, and scalability.
+
+  * [**Execution**](https://adidas-group.gitbooks.io/api-guidelines/content/execution/)
+
+    Execution qualities governance, such as security and usability.
+
+* **Guides**  
+  Guides and materials supporting the REST API Guidelines
+
+* **API Clients**
+
+  Section dedicated to consumers of adidas APIs
+
+
+

rest/core-principles/openapi-specification.md

@@ -0,0 +1,7 @@
+# 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).
+
+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.
+
+## Language
+The API description MUST be written in **American English**.

rest/core-principles/testing.md

@@ -0,0 +1,4 @@
+# Testing – Contract Validation
+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/). 
+
+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.