Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-25 15:19:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

GITBOOK-2: No subject

Browse Source
This commit is contained in:
Cesareo
2024-05-10 09:32:22 +00:00
committed by gitbook-bot
parent 2a0df79e63
commit b1e72ce21d
70 changed files with 529 additions and 676 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
general-guidelines/api-first.md
View File

@@ -2,9 +2,8 @@
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.
The API first principle is an extension of design-first principle. Therefore, a development of an API **MUST** always start with API design without any upfront coding activities.
**API design** \(e.g., description, schema\) **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 design which represents the [contract](contract.md) between API, and it's consumer.

5
general-guidelines/c_immutability.md Normal file
View File

@@ -0,0 +1,5 @@
# Immutability
After agreement with the stakeholders the contract **MUST** be published in the API registry in order to make it (that version) immutable. 
API registry acts as a central location for storing and accessing of all published APIs.

14
general-guidelines/d_data_types.md Normal file
View File

@@ -0,0 +1,14 @@
# Common Data Types
The API types **MUST** adhere to the formats defined below:
| Data type | Standard | Example |
| -------------- | ------------------------------------------------------------------------ | ----------------------------------------- |
| Date and Time | [ISO 8601](https://en.wikipedia.org/wiki/ISO\_8601) | 2017-06-21T14:07:17Z (Always use UTC) |
| Date | [ISO 8601](https://en.wikipedia.org/wiki/ISO\_8601) | 2017-06-21 |
| Duration | [ISO 8601](https://en.wikipedia.org/wiki/ISO\_8601) | P3Y6M4DT12H30M5S |
| Time interval | [ISO 8601](https://en.wikipedia.org/wiki/ISO\_8601) | 2007-03-01T13:00:00Z/2008-05-11T15:30:00Z |
| Timestamps | [ISO 8601](https://en.wikipedia.org/wiki/ISO\_8601) | 2017-01-01T12:00:00Z |
| Language Codes | [ISO 639](https://en.wikipedia.org/wiki/List\_of\_ISO\_639-1\_codes) | en <-> English |
| Country Code | [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2) | DE <-> Germany |
| Currency | [ISO 4217](https://en.wikipedia.org/wiki/ISO\_4217) | EUR <-> Euro |

10
general-guidelines/general-guidelines.md
View File

@@ -2,5 +2,13 @@
## 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.
In the scope of a company, organization or team, the document known as guidelines is a set of best practices or hints provided by a group of subject matter experts in that particular technology. The most important aspects of it:
* Help to create a standardized way of completing specific tasks, making outcome more predictable and alike
* Help to identify do's and dont's with regards to a specific technology or tool
* Help to avoid gotchas or problems related with company specifics
* Gather the knowledge of several Subject Matter Experts and prevent others for falling in frequent caveats or mistakes
This is a set of general rules and recommendations that have to be followed along the entire API lifecycle of any API regardless of its type.
**Note** In any case, the content in the guidelines should be taken as recommendations, not something that needs to be done in a mandatory way.

5
general-guidelines/n_tooling.md Normal file
View File

@@ -0,0 +1,5 @@
# Tooling
The current platform available in adidas to design, host, and render APIs specifications is [Swaggerhub](https://design.api.3stripes.io/).
Every API specification **MUST** be hosted in Swaggerhub under the _adidas_ organization.