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:
oonovak
2017-02-13 16:13:14 +00:00
parent cef5bfc5a4
commit 1a91434071
1 changed files with 11 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -1,17 +1,19 @@
# API First
Development of an API **MUST** always start with **API design** without any 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 [API design platform](./apiary.md).
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).
> NOTE: It's not acceptable that API is developed first and later on described in some proprietary format.
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 master of truth, not the API implementation.**
It's MUST to adhere to the statement above as this is basis for adoption of Microservice architecture pattern. It's absolute MUST that implementation never brea
1. API design SHOULD be realized following the **API design process**.
1. An API design MUST be formalized in a form of an API description using **Swagger** and stored in [Apiary](./apiary.md) before any coding activity
1. **API description is master of truth, not the API implementation.**
> NOTE: API first approach is crucial when adopting the Microservice architecture.
Describing what API is supposed to do also helps all stakeholders to align and better understand what will be delivered at the end.
It's not acceptable that API is developed first and later on described in some proprietary format.