api-guidelines/core-principles/api-first.md

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 and stored in API design platform.

NOTE: It's not acceptable that API is developed first and later on described in some proprietary format.

1. API design SHOULD be realized following the API design process.
2. An API design MUST be formalized in a form of an API description using Swagger and stored in Apiary before any coding activity
3. 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.