From 37a3e8f85a162887117a4d0fe0ecc30437f4ee2e Mon Sep 17 00:00:00 2001 From: oonovak Date: Mon, 13 Feb 2017 16:48:19 +0000 Subject: [PATCH] Updates core-principles/openapi-specification.md Auto commit by GitBook Editor --- core-principles/api-first.md | 2 +- core-principles/apiary.md | 2 +- core-principles/openapi-specification.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/core-principles/api-first.md b/core-principles/api-first.md index 9e4593a..282355b 100644 --- a/core-principles/api-first.md +++ b/core-principles/api-first.md @@ -4,7 +4,7 @@ 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 description platform](./apiary.md) and agreed by all stakeholders. +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. 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. diff --git a/core-principles/apiary.md b/core-principles/apiary.md index 77761bd..dd7656e 100644 --- a/core-principles/apiary.md +++ b/core-principles/apiary.md @@ -1,4 +1,4 @@ -# API description platform - Apiary +# API design platform - Apiary 1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](./api-first.md). Apiary MUST be used during API Design. 1. Every API description MUST be stored in [Apiary](https://apiary.io/) under the ADIDAS GROUP team. 1. Apiary MUST be the **single source of truth** to learn about existing APIs within the organization. diff --git a/core-principles/openapi-specification.md b/core-principles/openapi-specification.md index 871c821..363d62b 100644 --- a/core-principles/openapi-specification.md +++ b/core-principles/openapi-specification.md @@ -1,7 +1,7 @@ # OpenAPI Specification Every API **MUST** be described using an API description format. The API description format used MUST be the [OpenAPI Specification (formerly known as Swagger Specification) version 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md). Every API description **MUST** be: -* published in adidas [API description platform](./apiary.md) +* published in adidas [API design platform](./apiary.md) * stored in version control system (Bitbucket, GitHub) in the same repository as the API implementation. * accessible via endpoint through GET operation. _To be discussed_