diff --git a/README.md b/README.md index f0fcf15..6d8de92 100644 --- a/README.md +++ b/README.md @@ -3,10 +3,6 @@ # 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. @@ -15,13 +11,39 @@ The guidelines lay down the foundation for collaboration, stability and extensib ## Guidelines The API Guidelines are split into several levels: -![layers](/assets/layersfull.png) +- **Core Principles** -The **Core Principles** define the general rules that MUST be followed at throughout the full API lifecycle at any level. **Protocol guidelines** define the protocols used within the organization. The **Message guidelines** define the structure and semantics of messages used to exchange information. The **Application guidelines** define the definition and use of application-specific semantics. Finally, **Evolution and Execution guidelines** define the rules for achieving the desired architectural qualities of systems. + The Core Principle define the general rules that MUST be followed at throughout the full API lifecycle at any level. ---- +- **Functionality Guidelines** + - **Protocol level** + + Protocol guidelines define the protocols used within the organization. + + - **Message level ** + + The Message guidelines define the structure and semantics of messages used to exchange information. -These Guidelines are available for online reading at [GitBook](https://apidesigner.gitbooks.io/adidas-api-guidelines/content/). The source can be found on [GitHub](https://github.com/adidas-group/api-guidelines). + - **Application level** + + 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** + + Evolution qualities governance, such as testability, maintainability, extensibility and scalability. + + - **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). The CAPITALIZED words throughout these guidelines have a special meaning: @@ -34,7 +56,6 @@ The CAPITALIZED words throughout these guidelines have a special meaning: 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._