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

GitBook: [master] 102 pages and one asset modified

Browse Source
This commit is contained in:
apidesigner
2018-07-23 07:49:01 +00:00
committed by gitbook-bot
parent af88d15fd0
commit 3b81882249
68 changed files with 850 additions and 712 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
rest-api-guidelines/core-principles/README.md Normal file
View File

@@ -0,0 +1,4 @@
# Core Principles
This section outlines the foundation upon which the API Guidelines are built.

12
rest-api-guidelines/core-principles/apiary.md Normal file
View File

@@ -0,0 +1,12 @@
# API Design Platform
1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](https://github.com/adidas-group/api-guidelines/tree/af88d15fd04ef18d6724fa65943901aab7328e7f/rest/core-principles/api-first.md). Apiary **MUST** be used during API Design.
2. Every API description **MUST** be stored in [Apiary](https://apiary.io/) under the ADIDAS GROUP team.
3. 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\)
>
> NOTE: The synchronization between the version control system and adidas [API Description platform](apiary.md)
> should be automated using CI/CD framework.

18
rest-api-guidelines/core-principles/design-maturity.md Normal file
View File

@@ -0,0 +1,18 @@
# Design Maturity
## API Design Maturity
> How to design an API
Every API design **MUST** be **resource-centric** \([Web API Design Maturity Model Level 2](http://amundsen.com/talks/2016-11-apistrat-wadm/2016-11-apistrat-wadm.pdf)\). That is an API design **MUST** revolve around Web-styled _resources_, _relations_ between the resources and the _actions_ the resources may afford.
An API design **MAY** be **affordance-centric** \([Web API Design Maturity Model Level 3](http://amundsen.com/talks/2016-11-apistrat-wadm/2016-11-apistrat-wadm.pdf)\).
## API Design Implementation Maturity
> How to implement the API design
Every API design implementation using the HTTP 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)\).

10
rest-api-guidelines/core-principles/openapi-specification.md Normal file
View File

@@ -0,0 +1,10 @@
# 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 design platform](apiary.md) and it **SHOULD** be stored in version control system \(Bitbucket, GitHub\) in the same repository as the API implementation.
## Language
The API description MUST be written in **American English**.

6
rest-api-guidelines/core-principles/testing.md Normal file
View File

@@ -0,0 +1,6 @@
# Testing
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.