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
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)

4
core-principles/contract.md
View File

@@ -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).
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
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)).

2
core-principles/robustness.md
View File

@@ -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._
>

4
core-principles/testing.md
View File

@@ -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.

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

@@ -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.