Updates core-principles/apiary.md

Auto commit by GitBook Editor

README.md

@@ -19,40 +19,6 @@ The API Guidelines are split into two main parts:
 
 The general guidelines section discusses the core principles relevant to any kind of API. The API type-specific section further defines the guidelines specific to a given architectural style or API technique \(such as REST, Kafka or GraphQL API\).
 
-
-
-* The API Guidelines are split into several levels:
-
-* [**Core Principles**](https://adidas-group.gitbooks.io/api-guidelines/content/core-principles/)
-
-  Core Principles define the general rules that MUST be followed at throughout the full API lifecycle at any level.
-
-* **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.
-
 ## How to read the Guidelines
 
 These Guidelines are available for online reading at [GitBook](https://apidesigner.gitbooks.io/adidas-api-guidelines/content/) its source can be found on [GitHub](https://github.com/adidas-group/api-guidelines).

SUMMARY.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-* [Welcome](README.md)
+* [adidas API Guidelines](README.md)
 
 ## General Guidelines
 
@@ -12,7 +12,6 @@
 * [Robustness](core-principles/robustness.md)
 * [Minimal API Surface](core-principles/minimal-api-surface.md)
 * [Rules for Extending](core-principles/rules-for-extending.md)
-* [Foreign Key Relations](message/foreign-key-relations.md)
 * [JSON](evolution/json.md)
 * [Security](execution/security.md)
 
@@ -34,6 +33,7 @@
   * [Content Negotiation](message/content-negotiation.md)
   * [HAL](message/hal.md)
   * [Problem Detail](message/error-reporting.md)
+  * [Foreign Key Relations](message/foreign-key-relations.md)
 * [Application](application/README.md)
   * [Corporate Data Model](application/harmonize-data.md)
   * [Common Data Types](application/common-data-types.md)
@@ -59,7 +59,7 @@
 * [API Clients](clients/README.md)
   * [Loose Coupling](clients/loose-coupling.md)
 * [Examples](examples.md)
-* [Miscellaneous](miscellaneous.md)
+* Core Principles
 
 ## Kafka
 

core-principles/api-first.md

@@ -4,7 +4,7 @@ Everyone **MUST** follow the **API First** principle.
 
 The API first principle is an extension of contract-first principle. Therefore, a development of an API **MUST** always start with API design without any upfront coding activities.
 
-**API description is the master of truth, not the API implementation.**
+**API design **\(e.g., description, schema\)** is the master of truth, not the API implementation.**
 
-API implementation **MUST** always be compliant to particular API description which represents the [contract](./contract.md) between API, and it's consumer.
+API implementation **MUST** always be compliant to particular API design which represents the [contract](./contract.md) between API, and it's consumer.
 

core-principles/apiary.md

@@ -2,10 +2,15 @@
 
 1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](./api-first.md). Apiary **MUST** be used during API Design.
 
-1. Every API description **MUST** be stored in [Apiary](https://apiary.io/) under the ADIDAS GROUP team.
+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.
+
+
 
-1. 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)
-  

core-principles/contract.md

@@ -1,4 +1,6 @@
-# Contract 
-Approved API Design, represented by its API Description, **MUST** represent the **contract** between API stakeholder, implementers, and consumers.
+# Contract
+
+Approved API Design, represented by its API Description or schema, **MUST** represent the **contract** between API stakeholder, implementers, and consumers.
+
+Any change to an API **MUST** be accompanied by a related update to the contract \(API Design\).
 
-Any change to an API **MUST** be accompanied by a related update to the contract (API Description). 

core-principles/introduction.md

@@ -0,0 +1,38 @@
+# 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.
+
+
+

core-principles/version-control-system.md

@@ -1,7 +1,4 @@
 # Version Control System
-Every API description **SHOULD** be stored in a Version Control System (Bitbucket, GitHub). Where possible the API description **SHOULD** stored in the **same** repository as the API implementation.
-
-> NOTE: The synchronization between the version control system and adidas [API Description platform](./apiary.md) 
- should be automated using CI/CD framework. 
 
+Every API design **SHOULD** be stored in a Version Control System \(Bitbucket, GitHub\). Where possible the API design **SHOULD** stored in the **same** repository as the API implementation.
 

kafka/introduction.md

@@ -1,2 +1,4 @@
-Apache Kafka at adidas
+# adidas Kafka Guidelines
+
+