From 7502cbfd347020bfb0ab0ace1ac4803a3f67bbcb Mon Sep 17 00:00:00 2001 From: Andrzej Date: Tue, 26 Feb 2019 10:04:10 +0100 Subject: [PATCH 1/6] Add best practices on working with problem detail in oas --- rest-api-guidelines/functionality/message/error-reporting.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/rest-api-guidelines/functionality/message/error-reporting.md b/rest-api-guidelines/functionality/message/error-reporting.md index d854444..d6e22a7 100644 --- a/rest-api-guidelines/functionality/message/error-reporting.md +++ b/rest-api-guidelines/functionality/message/error-reporting.md @@ -122,5 +122,9 @@ A Problem Detail response **MUST NOT** contain a program stack trace or server l ## Working with Problem Detail +An API description **SHOULD** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code. + +## External resources + There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\). From 3afbf431037547556c09f53e387235baa5db2170 Mon Sep 17 00:00:00 2001 From: Andrzej Date: Tue, 26 Feb 2019 10:53:04 +0100 Subject: [PATCH 2/6] Add clarification on problem detail fields --- .../functionality/message/error-reporting.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/rest-api-guidelines/functionality/message/error-reporting.md b/rest-api-guidelines/functionality/message/error-reporting.md index d6e22a7..8ec785a 100644 --- a/rest-api-guidelines/functionality/message/error-reporting.md +++ b/rest-api-guidelines/functionality/message/error-reporting.md @@ -4,7 +4,7 @@ The [`application/problem+json`](https://tools.ietf.org/html/rfc7807) \(Problem Problem Detail is intended for use with the HTTP status codes 4xx and 5xx. Problem Detail **MUST NOT** be used with 2xx status code responses. -At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. +At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. `title` value **SHOULD NOT** change from occurrence to occurence of the problem, except for purposes of localization (e.g., using proactive content negotiation) [read more](https://tools.ietf.org/html/rfc7807#section-3.1) ### Example @@ -15,6 +15,8 @@ At the minimum, any Problem Detail response **MUST** have the `title` and `detai } ``` +> NOTE: `title` and `detail` fields **SHOULD NOT** be parsed to determine the nature of the error. Instead `type` **MUST** be used. + ## Optional Fields It **SHOULD** has the `type` field with the identifier of the error, besides it **MAY** have the `instance` field with the URI of the resource in question. If the Problem Detail response has the `status` field it **MUST** have the same value as HTTP Status code from of the response. @@ -39,7 +41,7 @@ If needed, the Problem Detail **MAY** include additional fields, refer to [RFC78 When necessary, a Problem Detail response **MAY** include additional error details about the problems that have occurred. -These additional errors **MUST** be under the `errors` and **MUST** follow the Problem Detail structure. +These additional errors **MUST** be under the `errors` collection and **MUST** follow the Problem Detail structure. ### Example @@ -126,5 +128,4 @@ An API description **SHOULD** list all the error codes with which the API respon ## External resources -There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\). - +There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\). \ No newline at end of file From dbfa603120bcb3d2d9e1990c27889f496712d1aa Mon Sep 17 00:00:00 2001 From: Andrzej Date: Thu, 11 Apr 2019 14:56:42 +0200 Subject: [PATCH 3/6] Rephrase working with problem detail section Now it does not oblige the contract to list all the errors --- rest-api-guidelines/functionality/message/error-reporting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rest-api-guidelines/functionality/message/error-reporting.md b/rest-api-guidelines/functionality/message/error-reporting.md index 8ec785a..45eae79 100644 --- a/rest-api-guidelines/functionality/message/error-reporting.md +++ b/rest-api-guidelines/functionality/message/error-reporting.md @@ -124,8 +124,8 @@ A Problem Detail response **MUST NOT** contain a program stack trace or server l ## Working with Problem Detail -An API description **SHOULD** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code. +An API description **CAN** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code. ## External resources -There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\). \ No newline at end of file +There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) \(Java\). From 71b489ccf1ae3f7d5ec9f6e5cf74f06e21d43efc Mon Sep 17 00:00:00 2001 From: Andrzej Date: Thu, 11 Apr 2019 15:17:06 +0200 Subject: [PATCH 4/6] fix undefined CAN usage CAN changed to MAY --- rest-api-guidelines/functionality/message/error-reporting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest-api-guidelines/functionality/message/error-reporting.md b/rest-api-guidelines/functionality/message/error-reporting.md index 45eae79..707eced 100644 --- a/rest-api-guidelines/functionality/message/error-reporting.md +++ b/rest-api-guidelines/functionality/message/error-reporting.md @@ -124,7 +124,7 @@ A Problem Detail response **MUST NOT** contain a program stack trace or server l ## Working with Problem Detail -An API description **CAN** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code. +An API description **MAY** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code. ## External resources From d79f8ff24531f7d3375bb4f9e5a447a497d87910 Mon Sep 17 00:00:00 2001 From: Jose Manuel Sampayo Date: Wed, 29 May 2019 16:28:44 +0200 Subject: [PATCH 5/6] + Adding references to Consumer Driven Contract Testing with PACT. nerea.tamayo@adidas.com josemanuel.sampayo@adidas.com --- general-guidelines/contract.md | 2 +- rest-api-guidelines/core-principles/testing.md | 12 ++++++++++++ 2 files changed, 13 insertions(+), 1 deletion(-) diff --git a/general-guidelines/contract.md b/general-guidelines/contract.md index f960c23..af27af0 100644 --- a/general-guidelines/contract.md +++ b/general-guidelines/contract.md @@ -2,5 +2,5 @@ Approved API Design, represented by its API Description or schema, **MUST** represent the **contract** between API stakeholder, implementers, and consumers. -Any change to an API **MUST** be accompanied by a related update to the contract \(API Design\). +An update to the corresponding contract \(API Design\) **MUST** be implemented and approved before any change to an API **MUST**. diff --git a/rest-api-guidelines/core-principles/testing.md b/rest-api-guidelines/core-principles/testing.md index b9b0e65..aa9af7b 100644 --- a/rest-api-guidelines/core-principles/testing.md +++ b/rest-api-guidelines/core-principles/testing.md @@ -1,6 +1,18 @@ # Testing +## DREED + 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. +## PACT + +Every adidas **CORE** API **MUST** be tested additionally applying Consumer Driven Contract Testing principles. The tests **MUST** be executed using the [PACT contract testing tool](https://docs.pact.io/). PACT tests **MUST** use adidas [PACT-Broker](http://pact.ati.adidas.com/) to store results and evidences. + +In addition to local runs, PACT tests **SHOULD** be an integral part of 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. + +Using Consumer Driven Contract Testing with PACT is *not mandatory* for adidas **NON-CORE** APIs, but strongly recommended due to the advantages this approach brings. It will be also a proof of our Software Engineering practices maturity. + +More information, guides and seeds about how to use PACT can be found on (internal link)[adidas Consumer Driven Contract Testing guide](https://tools.adidas-group.com/confluence/display/DSBP/adidas+Consumer+Driven+Contract+Testing+guide) page. + From 0e8aefcea21c5bd16c37343c4e160ef630b5df36 Mon Sep 17 00:00:00 2001 From: Jose Manuel Sampayo Date: Wed, 3 Jul 2019 12:37:43 +0200 Subject: [PATCH 6/6] = Fixing typo. --- rest-api-guidelines/core-principles/testing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rest-api-guidelines/core-principles/testing.md b/rest-api-guidelines/core-principles/testing.md index aa9af7b..3a8a172 100644 --- a/rest-api-guidelines/core-principles/testing.md +++ b/rest-api-guidelines/core-principles/testing.md @@ -1,6 +1,6 @@ # Testing -## DREED +## DREDD 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/).