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/apiary.md

Browse Source 
Auto commit by GitBook Editor
This commit is contained in:
apidesigner
2017-03-15 07:40:42 +00:00
parent 0e8c6586c5
commit 511d014509
6 changed files with 13 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

9
core-principles/apiary.md
View File

@@ -1,7 +1,10 @@
# API Design 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](https://apiary.io/) is the primary platform supporting [API first approach](./api-first.md). Apiary **MUST** be used during API Design.
1. Apiary MUST be the **single source of truth** to learn about existing APIs within the organization.
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: > 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) 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)

4
core-principles/contract.md
View File

@@ -1,4 +1,4 @@
# Contract # 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). Any change to an API **MUST** be accompanied by a relevant change in the contract (API Description).

2
core-principles/implementation-maturity.md
View File

@@ -1,4 +1,4 @@
# Implementation Maturity # 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)). An API design implementation SHOULD include **hypermedia controls** (HATEOAS) ([Richardson Maturity Model Level 3](https://martinfowler.com/articles/richardsonMaturityModel.html#level3)).

2
core-principles/robustness.md
View File

@@ -1,5 +1,5 @@
# Robustness # 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._ > _Be conservative in what you send, be liberal in what you accept._
> >

4
core-principles/testing.md
View File

@@ -1,4 +1,4 @@
# Testing – Contract Validation # 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.

2
core-principles/version-control-system.md
View File

@@ -1,2 +1,2 @@
# Version Control System # 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.