Merge pull request #5 from adidas-group/changes/5

Support for different architectural styles

README.md

@@ -1,49 +1,29 @@
 ![adidas logo](https://adidas-group.gitbooks.io/api-guidelines/content/assets/adidas-logo.svg)
 
 # adidas API Guidelines
-_Guidelines for API design at adidas_ ([Read online at GitBook](https://adidas-group.gitbooks.io/api-guidelines/content/))
+
+_Guidelines for API design at adidas_ \([Read online at GitBook](https://adidas-group.gitbooks.io/api-guidelines/content/)\)
 
 ## Motivation
+
 The goal of this document is to facilitate the work and minimize the effort of all API users while protecting their investment and encouraging API adoption.
 
 The guidelines lay down the foundation for collaboration, stability, and extensibility.
 
 ## Guidelines
-The API Guidelines are split into several levels:
 
-- **[Core Principles](https://adidas-group.gitbooks.io/api-guidelines/content/core-principles/)**
+The API Guidelines are split into two main parts:
 
-    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.
+* [General Guidelines](/general-guidelines/README.md)
+* API type-specific Guidelines
+  * [REST APIs Guidelines](/rest/README.md)
+  * [Kafka Guidelines](/kafka/README.md)
 
+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\).
 
 ## 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).
 
+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).
 
 The CAPITALIZED words throughout these guidelines have a special meaning:
 
@@ -57,4 +37,5 @@ Refer to [RFC2119](https://www.ietf.org/rfc/rfc2119) for details.
 
 ## Questions & Comments
 
-_Please contact [Zdenek.Nemec@externals.adidas-group.com](mailto:Zdenek.Nemec@externals.adidas-group.com) in the case of questions._
+_Please contact _[_Zdenek.Nemec@externals.adidas-group.com_](mailto:Zdenek.Nemec@externals.adidas-group.com)_ in the case of questions._
+

SUMMARY.md

@@ -1,56 +1,70 @@
 # Summary
 
-* [Introduction](README.md)
-* [Core Principles](core-principles/README.md)
-  * [API First](core-principles/api-first.md)
-  * [OpenAPI Specification](core-principles/openapi-specification.md)
-  * [API Design Platform](core-principles/apiary.md)
-  * [Version Control System](core-principles/version-control-system.md)
-  * [Contract](core-principles/contract.md)
-  * [Testing](core-principles/testing.md)
-  * [Design Maturity](core-principles/design-maturity.md)
-  * [Robustness](core-principles/robustness.md)
-  * [Minimal API Surface](core-principles/minimal-api-surface.md)
-  * [Rules for Extending](core-principles/rules-for-extending.md)
-* [Protocol](protocol/README.md)
-  * [HTTP](protocol/http.md)
-  * [TLS](protocol/tls.md)
-  * [Separate Concerns](protocol/separate-concerns.md)
-  * [Request Methods](protocol/use-appropriate-methods.md)
-  * [Status Codes](protocol/use-appropriate-status-codes.md)
-* [Message](message/README.md)
-  * [Message Formats](message/message-formats.md)
-  * [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)
-* [Evolution](evolution/README.md)
-  * [Naming Conventions](evolution/naming-conventions.md)
-  * [Reserved Identifiers](evolution/reserved-identifiers.md)
-  * [JSON](evolution/json.md)
-  * [Changes and Versioning](evolution/versioning.md)
-  * [URI Structure](evolution/uri-structure.md)
-  * [Testing Enviroments](execution/testing-enviroments.md)
-* [Execution](execution/README.md)
-  * [Pagination](execution/pagination.md)
-  * [Asynchronous Tasks](execution/asynchronous-tasks.md)
-  * [Batch Operations](execution/batch-operations.md)
-  * [Search Requests](execution/search-requests.md)
-  * [Query Requests with Large Inputs](execution/query-requests-with-large-inputs.md)
-  * [Choosing Fields and Embedded Resources](execution/choosing-fields-and-embedded-resoruces.md)
-  * [Localization](execution/localization.md)
-  * [Security](execution/security.md)
-  * [Rate Limiting](execution/rate-limiting.md)
-  * [Caching](execution/caching.md)
-* [API Clients](clients/README.md)
-  * [Loose Coupling](clients/loose-coupling.md)
-* [Guides](guides/README.md)
-  * [API Testing CI Environment](guides/api-testing-ci-environment.md)
-  * [Complete API Development](guides/complete-api-development.md)
-* [Examples](examples.md)
-* [Miscellaneous](miscellaneous.md)
-* [Acknowledgements](acknowledgements.md)
+## Introduction
+
+* [adidas API Guidelines](README.md)
+
+## General Guidelines
+
+* [Introduction](general-guidelines/README.md)
+* [API First](general-guidelines/api-first.md)
+* [Contract](general-guidelines/contract.md)
+* [Robustness](general-guidelines/robustness.md)
+* [Version Control System](general-guidelines/version-control-system.md)
+* [Minimal API Surface](general-guidelines/minimal-api-surface.md)
+* [Rules for Extending](general-guidelines/rules-for-extending.md)
+* [JSON](general-guidelines/json.md)
+* [Security](general-guidelines/security.md)
+
+## REST API Guidelines
+
+* [Introduction](rest/README.md)
+* [Core Principles](rest/core-principles/README.md)
+  * [OpenAPI Specification](rest/core-principles/openapi-specification.md)
+  * [API Design Platform](rest/core-principles/apiary.md)
+  * [Design Maturity](rest/core-principles/design-maturity.md)
+  * [Testing](rest/core-principles/testing.md)
+* [Functionality](core-principles/functional.md)
+  * [Protocol](rest/protocol/README.md)
+    * [HTTP](rest/protocol/http.md)
+    * [TLS](rest/protocol/tls.md)
+    * [Separate Concerns](rest/protocol/separate-concerns.md)
+    * [Request Methods](rest/protocol/use-appropriate-methods.md)
+    * [Status Codes](rest/protocol/use-appropriate-status-codes.md)
+  * [Message](rest/message/README.md)
+    * [Message Formats](rest/message/message-formats.md)
+    * [Content Negotiation](rest/message/content-negotiation.md)
+    * [HAL](rest/message/hal.md)
+    * [Problem Detail](rest/message/error-reporting.md)
+    * [Foreign Key Relations](rest/message/foreign-key-relations.md)
+  * [Application](rest/application/README.md)
+    * [Corporate Data Model](rest/application/harmonize-data.md)
+    * [Common Data Types](rest/application/common-data-types.md)
+* [Quality](rest/core-principles/quality.md)
+  * [Execution](rest/execution/README.md)
+    * [Pagination](rest/execution/pagination.md)
+    * [Asynchronous Tasks](rest/execution/asynchronous-tasks.md)
+    * [Batch Operations](rest/execution/batch-operations.md)
+    * [Search Requests](rest/execution/search-requests.md)
+    * [Query Requests with Large Inputs](rest/execution/query-requests-with-large-inputs.md)
+    * [Choosing Fields and Embedded Resources](rest/execution/choosing-fields-and-embedded-resoruces.md)
+    * [Localization](rest/execution/localization.md)
+    * [Rate Limiting](rest/execution/rate-limiting.md)
+    * [Caching](rest/execution/caching.md)
+  * [Evolution](rest/evolution/README.md)
+    * [Naming Conventions](rest/evolution/naming-conventions.md)
+    * [Reserved Identifiers](rest/evolution/reserved-identifiers.md)
+    * [URI Structure](rest/evolution/uri-structure.md)
+    * [Changes and Versioning](rest/evolution/versioning.md)
+    * [Testing Enviroments](rest/execution/testing-enviroments.md)
+* [Guides](rest/guides/README.md)
+  * [API Testing CI Environment](rest/guides/api-testing-ci-environment.md)
+  * [Complete API Development](rest/guides/complete-api-development.md)
+* [API Clients](rest/clients/README.md)
+  * [Loose Coupling](rest/clients/loose-coupling.md)
+* [Further References](rest/miscellaneous.md)
+
+## Kafka Guidelines
+
+* [Introduction](kafka/README.md)
 

core-principles/apiary.md

@@ -1,11 +0,0 @@
-# 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.
-
-1. Every API description **MUST** be stored in [Apiary](https://apiary.io/) under the ADIDAS GROUP team.
-
-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 +0,0 @@
-# Contract 
-Approved API Design, represented by its API Description, **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 Description). 

core-principles/version-control-system.md

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

general-guidelines/README.md

@@ -0,0 +1,6 @@
+# ![](/assets/adidas-logo.svg)
+
+# adidas General API Guidelines
+
+Set of general rules and recommendations that have to be followed along the entire API lifecycle of any API regardless of its type.
+

general-guidelines/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.
 

general-guidelines/contract.md

@@ -0,0 +1,6 @@
+# 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\).
+

general-guidelines/version-control-system.md

@@ -0,0 +1,4 @@
+# Version Control System
+
+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/README.md

@@ -0,0 +1,6 @@
+# ![](/assets/adidas-logo.svg)
+
+# adidas Kafka Guidelines
+
+
+

miscellaneous.md

@@ -1,4 +0,0 @@
-# Miscellaneous
-
-- [Product tokens](https://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-16#section-6.3)
-- [Deprecating "X-"](https://tools.ietf.org/html/rfc6648)

rest/README.md

@@ -0,0 +1,47 @@
+# ![](/assets/adidas-logo.svg)
+
+# 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/README.md)
+
+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/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/miscellaneous.md

@@ -0,0 +1,7 @@
+# Miscellaneous
+
+* [Product tokens](https://tools.ietf.org/html/draft-ietf-httpbis-p1-messaging-16#section-6.3)
+* [Deprecating "X-"](https://tools.ietf.org/html/rfc6648)
+
+
+