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

Updates core-principles/api-first.md

Browse Source 
Auto commit by GitBook Editor
This commit is contained in:
apidesigner
2017-06-15 10:59:29 +00:00
parent 42b61c3731
commit ea75349464
1 changed files with 3 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
core-principles/api-first.md
View File

@@ -2,19 +2,12 @@
Everyone **MUST** follow the **API first** principle.
**API first** principle is extension of **Contract first** architecture principle.
Therefore development of an API **MUST** always start with **API design** without any upfront coding activities.
An API design **MUST** be formalized in a form of an **API description** using [Open API Specification](./openapi-specification.md) and stored in adidas [API design platform](./apiary.md) and agreed by all stakeholders.
The API first principle is extension of contract-first principle. Therefore, an development of an API **MUST** always start with API design without any upfront coding activities.
Clearly describing what API is supposed to do before coding it, helps to facilitate discussion between stakeholders and allows to receive feedback in early stage of the API development process.
It also helps to establish governance on API's to check that certain quality is met and API guidelines are being followed.
**API description is the master of truth, not the API implementation.**
**API description is master of truth, not the API implementation.**
API implementation **MUST** always be compliant to respective API description which represent the [Contract](./contract.md) between API and it's consumer.
API implementation **MUST** always be compliant to respective API description which represent the [contract](./contract.md) between API and it's consumer.
> NOTE:
* It's not acceptable that API is developed first and later on described in some proprietary format.
* It's not acceptable that API implementation doesn't implement it's description.