Merge branch 'master' into mit-badge

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,2 @@
+# Code of conduct
+Read the general [adidas code of conduct](https://github.com/adidas/adidas-contribution-guidelines/wiki/Contributing#code-of-conduct).

.github/CONTRIBUTING.md

@@ -0,0 +1,12 @@
+# Contributing
+First off, thanks for taking the time to contribute!
+
+To contribute to a adidas API Guidelines simply fork the repository, commit and push the changes and open a pull request. 
+
+## Review
+Note, however, that adidas API Guidelines are followed by architects and engineers at adidas and as such any **pull request needs to be reviewed and approved by adidas API team**.
+
+Some changes like typos, clarifications and examples can be approved relatively quick, however substantial changes, changes to the rules or addition of new rules are subject of a thorough review and approval process lead by the API team.
+
+## Rendering at GitBook
+The API guidelines are primarily intended for reading at <https://adidas.gitbook.io/api-guidelines/> and as such it needed to review the documentation rendering there, not in this GitHub repository (optimize for GitBook not GitHub).

README.md

@@ -1,18 +1,20 @@
+---
+description: Guidelines for the API design and development at adidas
+---
+
 # adidas API Guidelines
 
 ![adidas logo](https://adidas-group.gitbooks.io/api-guidelines/content/assets/adidas-logo.svg)
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-## About
-
-_Guidelines for API design and development at adidas_ \([Read online at GitBook](https://adidas.gitbook.io/api-guidelines/)\)
+[Read online at GitBook](https://adidas.gitbook.io/api-guidelines/)
 
 ### 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 goal of this document is to facilitate the work and minimize the effort of all API users at adidas while protecting their investment and encouraging API adoption.
 
-The guidelines lay down the foundation for collaboration, stability, and extensibility.
+These guidelines lay down the foundation for collaboration, stability, and extensibility.
 
 ### Guidelines
 
@@ -23,11 +25,11 @@ The API Guidelines are split into two main parts:
   * [REST APIs Guidelines](rest-api-guidelines/rest.md)
   * [Kafka Guidelines](kafka-guidelines/kafka.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\).
+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 APIs\).
 
 ### 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://adidas.gitbook.io/api-guidelines/) its source can be found on [GitHub](https://github.com/adidas/api-guidelines).
 
 The CAPITALIZED words throughout these guidelines have a special meaning:
 
@@ -43,3 +45,25 @@ Refer to [RFC2119](https://www.ietf.org/rfc/rfc2119) for details.
 
 _Please contact_ [_Zdenek.Nemec@externals.adidas-group.com_](mailto:Zdenek.Nemec@externals.adidas-group.com) _in the case of questions._
 
+## Intended Use Cases
+
+This project is intended to provide the guidelines for design & development of APIs at adidas.
+
+adidas is not responsible for the usage of this software for different purposes that the ones described in the use cases.
+
+## License and Software Information
+
+© adidas AG
+
+adidas AG publishes this software and accompanied documentation \(if any\) subject to the terms of the MIT license with the aim of helping the community with our tools and libraries which we think can be also useful for other people. You will find a copy of the MIT license in the root folder of this package. All rights not explicitly granted to you under the MIT license remain the sole and exclusive property of adidas AG.
+
+NOTICE: The software has been designed solely for the purpose of providing API design and development guidelines. The software is NOT designed, tested or verified for productive use whatsoever, nor or for any use related to high risk environments, such as health care, highly or fully autonomous driving, power plants, or other critical infrastructures or services.
+
+If you want to contact adidas regarding the software, you can mail us at _software.engineering@adidas.com_.
+
+For further information open the [adidas terms and conditions](https://github.com/adidas/adidas-contribution-guidelines/wiki/Terms-and-conditions) page.
+
+### License
+
+[MIT](https://github.com/adidas-group/api-guidelines/tree/657bc6fd49f1499f10c30ab18420f4bdb7cd841b/LICENSE/README.md)
+

SUMMARY.md

@@ -1,10 +1,6 @@
 # Table of contents
 
-* [Introduction](README.md)
-
-## Introduction
-
-* [adidas API Guidelines](introduction/readme.md)
+* [adidas API Guidelines](README.md)
 
 ## General Guidelines
 
@@ -53,12 +49,13 @@
     * [Localization](rest-api-guidelines/quality/execution/localization.md)
     * [Rate Limiting](rest-api-guidelines/quality/execution/rate-limiting.md)
     * [Caching](rest-api-guidelines/quality/execution/caching.md)
+    * [Testing Enviroments](rest-api-guidelines/quality/execution/testing-enviroments.md)
   * [Evolution](rest-api-guidelines/quality/evolution/README.md)
     * [Naming Conventions](rest-api-guidelines/quality/evolution/naming-conventions.md)
     * [Reserved Identifiers](rest-api-guidelines/quality/evolution/reserved-identifiers.md)
     * [URI Structure](rest-api-guidelines/quality/evolution/uri-structure.md)
     * [Changes and Versioning](rest-api-guidelines/quality/evolution/versioning.md)
-    * [Testing Enviroments](rest-api-guidelines/quality/evolution/testing-enviroments.md)
+    * [Phasing out Old Versions](rest-api-guidelines/quality/evolution/phasing-out-old-versions.md)
 * [Guides](rest-api-guidelines/guides/README.md)
   * [API Testing CI Environment](rest-api-guidelines/guides/api-testing-ci-environment.md)
   * [Complete API Development](rest-api-guidelines/guides/complete-api-development.md)

introduction/readme.md

@@ -1,43 +0,0 @@
-# adidas API Guidelines
-
-![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/)\)
-
-### 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 two main parts:
-
-* [General Guidelines](../general-guidelines/general-guidelines.md)
-* API type-specific Guidelines
-  * [REST APIs Guidelines](../rest-api-guidelines/rest.md)
-  * [Kafka Guidelines](../kafka-guidelines/kafka.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).
-
-The CAPITALIZED words throughout these guidelines have a special meaning:
-
-> ```text
-> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
-> "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in 
-> this document are to be interpreted as described in RFC2119.
-> ```
-
-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._
-

rest-api-guidelines/functionality/README.md

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

rest-api-guidelines/quality/evolution/phasing-out-old-versions.md

@@ -0,0 +1,38 @@
+# Phasing out Old Versions
+
+An older resource variant or action **MAY** be phased out and eventually removed providing clients were given enough time to accommodate for the change.
+
+Whether a resource or action can be phased out and removed completely depends on the nature of the API and the importance of existing integrations. 
+
+If an interface might be phased out it **MUST** follow the Phasing out Outline as specified in these guidelines. 
+
+> The gist is to never break existing clients. As soon as there is a breaking change a new resource variant should be created leaving the original intact to not break existing integrations. However, over the time it might be desired to remove older, unused variants.
+
+### Phasing out Outline
+
+#### 1. Mark as Deprecated
+
+The deprecation mark **SHOULD** happen both at runtime and in the documentation. 
+
+For the runtime deprecation notice the  [HTTP Sunset Header](https://tools.ietf.org/id/draft-wilde-sunset-header-03.html) **MUST** be used. For the documentation, the resource or action **MUST** be clearly marked in its description as deprecated.
+
+#### 2. Inform Users
+
+Existing API users **MUST** be noticed by available means about the deprecation of the interface. They **SHOULD** be informed about what are the alternatives to using the deprecated functionality and what is the migration path.
+
+#### 3. Remove Documentation of the Deprecated Interface
+
+Eventually, the part of API documentation describing the deprecated interface **MAY** be removed or hidden to prevent new users from using the deprecated resources or actions. 
+
+#### 4. Final Notice
+
+After a sufficient grace period a final deprecation notice **SHOULD** be issued.
+
+#### 5. Remove Deprecated Interface
+
+When there are no users using the deprecated interface, the interface **MAY** be decommissioned. A deprecated resource or action **MUST NOT** be removed if there are known existing integrations using it.
+
+Based one the nature of migration path a redirect to a new variant **SHOULD** be provided.
+
+> Phasing-out, depends on the importance of the APIs and its audience, for business-critical APIs, one never want to risk removing anything. For example [Stripe.com](http://stripe.com/) maintain all past versions. For other, less critical APIs, or APIs where one control its client\(s\), one can be more relaxed about removing deprecated resources.
+