From c07fc4057d89ba2ec1bb62c7208167ba035023d4 Mon Sep 17 00:00:00 2001 From: apidesigner Date: Mon, 30 Jan 2017 11:51:29 +0000 Subject: [PATCH] Updates core-principles/design-maturity.md Auto commit by GitBook Editor --- SUMMARY.md | 2 +- core-principles/apiary.md | 1 + core-principles/design-maturity.md | 4 ++-- core-principles/implementation-maturity.md | 4 ++++ core-principles/openapi-specification.md | 4 +++- core-principles/testing.md | 3 ++- core-principles/version-control-system.md | 2 +- 7 files changed, 14 insertions(+), 6 deletions(-) create mode 100644 core-principles/implementation-maturity.md diff --git a/SUMMARY.md b/SUMMARY.md index fc96fce..c840c30 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -9,5 +9,5 @@ * [Contract](core-principles/contract.md) * [Testing](core-principles/testing.md) * [Design Maturity](core-principles/design-maturity.md) - * Implementation Maturity + * [Implementation Maturity](core-principles/implementation-maturity.md) diff --git a/core-principles/apiary.md b/core-principles/apiary.md index aec6fd1..ff7d9ae 100644 --- a/core-principles/apiary.md +++ b/core-principles/apiary.md @@ -1,3 +1,4 @@ # Apiary Every API description MUST to be stored in [Apiary](https://apiary.io/) under the ADIDAS GROUP team. Apiary MUST be the single source of truth to learn about existing APIs within the organization. +(TODO: see Apiary Appendix) diff --git a/core-principles/design-maturity.md b/core-principles/design-maturity.md index d311ed2..83e8b88 100644 --- a/core-principles/design-maturity.md +++ b/core-principles/design-maturity.md @@ -1,7 +1,7 @@ # Design Maturity -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 HTTP-styled resources, relations between the resources and actions the resources afford. +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 might 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)). -(TODO: see API Design Process Appendix) \ No newline at end of file +(TODO: see API Design Process Appendix) diff --git a/core-principles/implementation-maturity.md b/core-principles/implementation-maturity.md new file mode 100644 index 0000000..89c8ce2 --- /dev/null +++ b/core-principles/implementation-maturity.md @@ -0,0 +1,4 @@ +# Implementation Maturity +Every API design using the HTTP(S) protocol MUST implement any action afforded by a resource using the appropriate HTTP Request Method semantics. + + diff --git a/core-principles/openapi-specification.md b/core-principles/openapi-specification.md index cb75891..578cb7a 100644 --- a/core-principles/openapi-specification.md +++ b/core-principles/openapi-specification.md @@ -2,4 +2,6 @@ Every API MUST be described using 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). ## Language -The API description MUST be written in U.S. English. \ No newline at end of file +The API description MUST be written in U.S. English. + +(TODO: see OpenAPI Appendix) \ No newline at end of file diff --git a/core-principles/testing.md b/core-principles/testing.md index 8d36054..712e3d1 100644 --- a/core-principles/testing.md +++ b/core-principles/testing.md @@ -1,6 +1,7 @@ # Testing – Contract Validation -Every API description (contract) SHOULD 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. +(TODO: see Testing and CI/CD Appendix) \ No newline at end of file diff --git a/core-principles/version-control-system.md b/core-principles/version-control-system.md index e0245e1..62280d5 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. \ No newline at end of file +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.