mirror of
https://github.com/adidas/api-guidelines.git
synced 2025-10-25 15:19:19 +00:00
74 lines
2.9 KiB
Markdown
74 lines
2.9 KiB
Markdown
|
|
|
|
# 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
|
|
* API type-specific Guidelines
|
|
|
|
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).
|
|
|
|
The CAPITALIZED words throughout these guidelines have a special meaning:
|
|
|
|
> ```
|
|
> 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._
|
|
|