From 511d01450969c9abfdfeeedefe334ae4f40ca1de Mon Sep 17 00:00:00 2001 From: apidesigner Date: Wed, 15 Mar 2017 07:40:42 +0000 Subject: [PATCH] Updates core-principles/apiary.md Auto commit by GitBook Editor --- core-principles/apiary.md | 9 ++++++--- core-principles/contract.md | 4 ++-- core-principles/implementation-maturity.md | 2 +- core-principles/robustness.md | 2 +- core-principles/testing.md | 4 ++-- core-principles/version-control-system.md | 2 +- 6 files changed, 13 insertions(+), 10 deletions(-) diff --git a/core-principles/apiary.md b/core-principles/apiary.md index 01a2e1e..3e34399 100644 --- a/core-principles/apiary.md +++ b/core-principles/apiary.md @@ -1,7 +1,10 @@ # 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. + +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. > NOTE: Apiary supports API first approach in multiple ways: a. Validates API description for correctness and automatically generates API documentation to drive the discussion between stakeholders. (No more emails with API description flying between stakeholders) diff --git a/core-principles/contract.md b/core-principles/contract.md index 8eeb7eb..ecb933a 100644 --- a/core-principles/contract.md +++ b/core-principles/contract.md @@ -1,4 +1,4 @@ # Contract -Approved API Design, represented by its API Description, MUST represent the **contract** between API stakeholder, implementers and consumers. +Approved API Design, represented by its API Description, **MUST** represent the **contract** between API stakeholder, implementers and consumers. -Any change to an API MUST be accompanied by a relevant change in the contract (API Description). \ No newline at end of file +Any change to an API **MUST** be accompanied by a relevant change in the contract (API Description). \ No newline at end of file diff --git a/core-principles/implementation-maturity.md b/core-principles/implementation-maturity.md index a4c4974..ffaf982 100644 --- a/core-principles/implementation-maturity.md +++ b/core-principles/implementation-maturity.md @@ -1,4 +1,4 @@ # Implementation Maturity -Every API design using the HTTP(S) protocol MUST use the appropriate **HTTP Request Method** ([Richardson Maturity Model Level 2](https://martinfowler.com/articles/richardsonMaturityModel.html#level2)) to implement an action afforded by a resource. +Every API design using the HTTP(S) protocol **MUST** use the appropriate **HTTP Request Method** ([Richardson Maturity Model Level 2](https://martinfowler.com/articles/richardsonMaturityModel.html#level2)) to implement an action afforded by a resource. An API design implementation SHOULD include **hypermedia controls** (HATEOAS) ([Richardson Maturity Model Level 3](https://martinfowler.com/articles/richardsonMaturityModel.html#level3)). diff --git a/core-principles/robustness.md b/core-principles/robustness.md index 093f410..4c4efd0 100644 --- a/core-principles/robustness.md +++ b/core-principles/robustness.md @@ -1,5 +1,5 @@ # Robustness -Every API implementation and API consumer MUST follow Postel's law: +Every API implementation and API consumer **MUST** follow Postel's law: > _Be conservative in what you send, be liberal in what you accept._ > diff --git a/core-principles/testing.md b/core-principles/testing.md index c0bf4f6..9a8ca38 100644 --- a/core-principles/testing.md +++ b/core-principles/testing.md @@ -1,4 +1,4 @@ # Testing – Contract Validation -Every API description (contract) using HTTP(S) protocol MUST be tested against its API implementation. The tests MUST be executed using the [Dredd testing framework](https://github.com/apiaryio/dredd). The Dredd MUST [report the test results to Apiary](https://help.apiary.io/tools/automated-testing/testing-reporter/). +Every API description (contract) using HTTP(S) protocol **MUST** be tested against its API implementation. The tests **MUST** be executed using the [Dredd testing framework](https://github.com/apiaryio/dredd). The Dredd **MUST** [report the test results to Apiary](https://help.apiary.io/tools/automated-testing/testing-reporter/). -In addition to local runs, the tests SHOULD be an integral part the API implementation's CI/CD pipeline. The CI/CD pipeline SHOULD be configured to run the test whenever there is a change to either API description (contract) or its implementation. +In addition to local runs, the tests **SHOULD** be an integral part the API implementation's CI/CD pipeline. The CI/CD pipeline **SHOULD** be configured to run the test whenever there is a change to either API description (contract) or its implementation. diff --git a/core-principles/version-control-system.md b/core-principles/version-control-system.md index 62280d5..7a4579b 100644 --- a/core-principles/version-control-system.md +++ b/core-principles/version-control-system.md @@ -1,2 +1,2 @@ # Version Control System -Every API description SHOULD be stored in a Version Control System (Bitbucket, GitHub). Where possible the API description SHOULD stored in the **same** repository as the API implementation. +Every API description **SHOULD** be stored in a Version Control System (Bitbucket, GitHub). Where possible the API description **SHOULD** stored in the **same** repository as the API implementation.