From a6d7fc63de2438adb0415412c0295f740afac679 Mon Sep 17 00:00:00 2001 From: Cesareo Macias Date: Wed, 12 Feb 2025 16:37:20 +0000 Subject: [PATCH 1/8] GITBOOK-1: No subject --- .gitbook/assets/adidas_company_logo_BWp.png | Bin 0 -> 3346 bytes .gitbook/assets/adidas_company_logo_BWr.png | Bin 0 -> 3026 bytes README.md | 54 ++++++++++-------- .../guides/api-testing-ci-environment.md | 50 ++++++++-------- 4 files changed, 53 insertions(+), 51 deletions(-) create mode 100644 .gitbook/assets/adidas_company_logo_BWp.png create mode 100644 .gitbook/assets/adidas_company_logo_BWr.png diff --git a/.gitbook/assets/adidas_company_logo_BWp.png b/.gitbook/assets/adidas_company_logo_BWp.png new file mode 100644 index 0000000000000000000000000000000000000000..e80f81abf3395b2042bf966507bce4f449636033 GIT binary patch literal 3346 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 Uu*~;j;s5{u07*qoM6N<$g1V>F+yDRo literal 0 HcmV?d00001 diff --git a/README.md b/README.md index 790f55e..bf86ef4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # adidas API Guidelines -![adidas logo](adidaslogo.jpg) + + +
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) @@ -8,7 +10,7 @@ ### Motivation -The goal of this document is to facilitate the work and minimize the effort of all API users at adidas while protecting their investment and encouraging API adoption. +The goal of this document is to facilitate the work and minimize the effort of all API users at adidas while protecting their investment and encouraging API First adoption. These guidelines lay down the foundation for collaboration, stability, and extensibility. @@ -19,13 +21,15 @@ The API Guidelines are split into two main parts: * [General Guidelines](general-guidelines/general-guidelines.md) * API type-specific Guidelines * [REST APIs Guidelines](rest-api-guidelines/rest.md) - * [Asynchronous APIs Guidelines](asynchronous-api-guidelines/index.md) + * [Asynchronous APIs Guidelines](https://github.com/cesareomacias/api-guidelines/blob/master/asynchronous-api-guidelines/index.md) -The general guidelines section discusses the core principles relevant to any kind of API. The API type-specific section further defines the guidelines specific to a given architectural style or API technique (such as REST, Kafka or GraphQL APIs). +The general guidelines section discusses the core principles relevant to any kind of API. + +The API type-specific section further defines the guidelines specific to a given architectural style or API technique (such as REST, Kafka or GraphQL APIs). ### How to read the Guidelines -These Guidelines are available for online reading at [GitBook](https://adidas.gitbook.io/api-guidelines/). The source code can be found on [GitHub](https://github.com/adidas/api-guidelines). +These guidelines are available for online reading at [GitBook](https://adidas.gitbook.io/api-guidelines/). The source code can be found on [GitHub](https://github.com/adidas/api-guidelines). The CAPITALIZED words throughout these guidelines have a special meaning: @@ -35,41 +39,47 @@ The CAPITALIZED words throughout these guidelines have a special meaning: > this document are to be interpreted as described in RFC2119. > ``` -Refer to [RFC2119](https://www.ietf.org/rfc/rfc2119) for details. +Refer to [RFC2119](https://www.rfc-editor.org/rfc/rfc2119) for details. ### Validating your API Guidelines against OpenAPI Specification -In the `ruleset.md` file you can find a digest of API Guidelines rules which you can use to validate your API description documents. If you are using OpenAPI Specification as the API description format you can also leverage the `.spectral.yaml` ruleset to automatically verify your specification compliance using [Spectral](github.com/stoplightio/spectral/). +In the `ruleset.md` file you can find a digest of API Guidelines rules which you can use to validate your API description documents. -To install Spectral you will need Node.js and a package manager (npm or yarn). +If you are using OpenAPI or AsyncAPI specification as API description format, you can also leverage the `adidas-spectral.yaml` ruleset to automatically lint your specification compliance using [Spectral](https://meta.stoplight.io/docs/spectral/674b27b261c3c-overview). -Note: The version used with the spectral specifications was 5.3.0 +> To install Spectral, you will need Node.js and a package manager (npm or yarn). -``` -npm install -g @stoplight/spectral@5.3.0 +```bash +npm install -g @stoplight/spectral-cli # OR -yarn global add @stoplight/spectral@5.3.0 +yarn global add @stoplight/spectral-cli ``` -Once installed, to verify your OAS file with spectral execute `spectral lint -r /.spectral.yaml` where `/.spectral.yaml` indicated the location `.spectral.yaml` file. +Once installed, to verify your _oas_ or _async_ file with spectral execute: -For further documentation on Spectral refer to their [documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/README.md). +```bash +spectral lint --ruleset adidas-spectral.yaml +``` -### Questions & Comments +### Contact Us -_Please contact_ [_jesusjavier.dediego@adidas.com_](mailto:jesusjavier.dediego@adidas.com) _in case of questions._ +In case you have any questions or comments, please utilize the appropriate GitHub collaboration tools, such as issues, pull requests, and discussions. + +If you want to contact adidas API Team regarding these guidelines, you can mail us at + + _**api-team@adidas.com**_ ## Intended Use Cases This project is intended to provide the guidelines for design & development of APIs at adidas. -adidas is not responsible for the usage of this software for different purposes that the ones described in the use cases. +Adidas is not responsible for the usage of this software for different purposes that the ones described in the use cases. ## Last Review -May 2024 +February 2025 ## License and Software Information @@ -77,12 +87,6 @@ May 2024 adidas AG publishes this software and accompanied documentation (if any) subject to the terms of the MIT license with the aim of helping the community with our tools and libraries which we think can be also useful for other people. You will find a copy of the MIT license in the root folder of this package. All rights not explicitly granted to you under the MIT license remain the sole and exclusive property of adidas AG. -NOTICE: The software has been designed solely for the purpose of providing API design and development guidelines. The software is NOT designed, tested or verified for productive use whatsoever, nor or for any use related to high risk environments, such as health care, highly or fully autonomous driving, power plants, or other critical infrastructures or services. - -If you want to contact adidas regarding the software, you can mail us at _software.engineering@adidas.com_. +NOTICE: The software has been designed solely for the purpose of providing API design and development guidelines. The software is NOT designed, tested or verified for productive use whatsoever, nor or for any use related to high-risk environments, such as health care, highly or fully autonomous driving, power plants, or other critical infrastructures or services. For further information open the [adidas terms and conditions](https://github.com/adidas/adidas-contribution-guidelines/wiki/Terms-and-conditions) page. - -### License - -[MIT](https://github.com/adidas/api-guidelines/blob/master/LICENSE) diff --git a/rest-api-guidelines/guides/api-testing-ci-environment.md b/rest-api-guidelines/guides/api-testing-ci-environment.md index 409f447..4943e72 100644 --- a/rest-api-guidelines/guides/api-testing-ci-environment.md +++ b/rest-api-guidelines/guides/api-testing-ci-environment.md @@ -1,28 +1,27 @@ # API Testing CI Environment -This guide describes steps necessary for testing an API described in a swagger file with the [Dredd API Testing Framework](https://github.com/apiaryio/dredd) in a CI Environment \(Jenkins, TeamCity\). +This guide describes steps necessary for testing an API described in a swagger file with the [Dredd API Testing Framework](https://github.com/apiaryio/dredd) in a CI Environment (Jenkins, TeamCity). ## Environment Prerequisites The following must be available in the CI environment before testing: -1. **Node.js** runtime MUST be available in the CI environment: +1. **Node.js** runtime MUST be available in the CI environment: - ```text - $ node -v - v14.15.5 - ``` + ``` + $ node -v + v14.15.5 + ``` +2. [**Dredd**](https://github.com/apiaryio/dredd) MUST be installed globally in the CI environment: -3. [**Dredd**](https://github.com/apiaryio/dredd) MUST be installed globally in the CI environment: + ``` + $ npm install -g dredd --no-optional + ``` - ```text - $ npm install -g dredd --no-optional - ``` - - ```text - $ dredd --version - dredd v14.0.0 - ``` + ``` + $ dredd --version + dredd v14.0.0 + ``` ## Testing an API @@ -30,23 +29,22 @@ The following must be available in the CI environment before testing: To test an API within the CI environment provisioned as mentioned in the environment prerequisites, you will need the following: -1. A `swagger.yaml` file with the description of API being tested +1. A `swagger.yaml` file with the description of API being tested - The OpenAPI Specifciation file should be fetched from [API Design Platform](design-plaform.md). In the case of SwaggerHub API Design Platform, the file can be fetched manually or via their API. Refer to [Integrating with the SwaggerHub API](https://swagger.io/blog/api-development/integrating-with-the-swaggerhub-api/), for details how to use SwaggerHub API. + The OpenAPI Specifciation file should be fetched from [API Design Platform](https://github.com/cesareomacias/api-guidelines/blob/master/rest-api-guidelines/guides/design-plaform.md). In the case of SwaggerHub API Design Platform, the file can be fetched manually or via their API. Refer to [Integrating with the SwaggerHub API](https://swagger.io/blog/api-development/integrating-with-the-swaggerhub-api/), for details how to use SwaggerHub API. - Alternativelly this can also be a remote file e.g. SwaggerHub URL, if the API is public its OAS file and reachable from the testing host. + Alternativelly this can also be a remote file e.g. SwaggerHub URL, if the API is public its OAS file and reachable from the testing host. +2. The host (address) of the service being tested -2. The host \(address\) of the service being tested - - ```text - $ export API_HOST=http://deheremap7336.emea.adsint.biz:8004` - ``` + ``` + $ export API_HOST=http://deheremap7336.emea.adsint.biz:8004` + ``` ### Running the Test Run: -```text +``` $ dredd swagger.yaml $API_HOST ``` @@ -54,8 +52,8 @@ $ dredd swagger.yaml $API_HOST The Dredd will perform the tests and exits usually if the tests have passed. You can check the test result as with any other Unix tools with: -```text +``` $ echo $? ``` -Everything else but `0` should break the build. The test results will be visible in the CLI \(log\) +Everything else but `0` should break the build. The test results will be visible in the CLI (log) From c5cf9a1de6db881a87520f3a2d2cb9b0a408b307 Mon Sep 17 00:00:00 2001 From: Cesareo <118807053+cesareomacias@users.noreply.github.com> Date: Thu, 13 Feb 2025 09:54:22 +0100 Subject: [PATCH 2/8] Update package.json --- package.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/package.json b/package.json index 5a14fbf..f76ae50 100644 --- a/package.json +++ b/package.json @@ -1,13 +1,13 @@ { "name": "api-guidelines", - "version": "1.0.0", + "version": "1.1.0", "description": "adidas API guidelines", - "repository": "git@github.com:adidas/api-guidelines.git", - "author": "software.engineering@adidas.com", + "repository": "https://github.com/adidas/api-guidelines", + "author": "api-team@adidas.com", "license": "MIT", "private": true, "dependencies": { - "@stoplight/spectral": "^5.3.0", + "@stoplight/spectral": "^6.13.1", "@supermodel/cli": "^0.46.29" }, "scripts": { From de51c99097e1906e9c2dc305473b512f5e1e09e3 Mon Sep 17 00:00:00 2001 From: Cesareo <118807053+cesareomacias@users.noreply.github.com> Date: Thu, 13 Feb 2025 09:57:10 +0100 Subject: [PATCH 3/8] Update validating-api-descriptions.md --- general-guidelines/validating-api-descriptions.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/general-guidelines/validating-api-descriptions.md b/general-guidelines/validating-api-descriptions.md index d8857ad..e377903 100644 --- a/general-guidelines/validating-api-descriptions.md +++ b/general-guidelines/validating-api-descriptions.md @@ -50,10 +50,9 @@ Spectral can also be used from within JavaScript. For details on how to accompli ## Validating with Adidas API Guidelines -To check whether your API Specification complies with Adidas API Guidelines you will need the `.spectral.yaml` file from this repository ([here](https://github.com/adidas/api-guidelines/blob/master/.spectral.yml)). - +To check whether your API Specification complies with Adidas API Guidelines you will need the `adidas-spectral.yaml` file from this repository ([here](https://github.com/adidas/api-guidelines/blob/master/adidas-spectral.yaml)). ``` -spectral lint -r /.spectral.yaml +spectral lint --ruleset adidas-spectral.yaml ``` ### Validation problems From 5c6596ddec84d93774022f7bd9e6c065ffb54a74 Mon Sep 17 00:00:00 2001 From: Cesareo <118807053+cesareomacias@users.noreply.github.com> Date: Thu, 13 Feb 2025 09:57:57 +0100 Subject: [PATCH 4/8] Delete adidaslogo.jpg --- adidaslogo.jpg | Bin 12722 -> 0 bytes 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 adidaslogo.jpg diff --git a/adidaslogo.jpg b/adidaslogo.jpg deleted file mode 100644 index 472ae051923b030b24672d60ca1e3ee77f54e29f..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 12722 zcmeHtXH-<%(%=D%C?Fu91mQMGn$Qv&=q4&T$0i3!B28|Zob`$XK^p`vNKhm;NziU2 zqvWhWlY``(qaZTv9rV68-+i-Yt@+-Mnf3Ocy-%I0+O=y}*t^a-89bQ;t||C9+yej= z6)%b%yv@xj_U4 zZb1M^86P(*8%H}do3)+2gNqbsy|Na>=3pxYGK6Z}(r}ZryYHavhqBZ2)6}=|bF_ik zf@GxGBz@pM&Th_jXe%}!XD1gAxQ`U*Pv&sq_y-sQV*3*X?I;Dh{bN=(BMogfIaib& z8&p7)-$qbSkWCCGAP5x~7J~Az3EdKeLTxURh7 z>0HDoDbVSnyuG~zyoCi^QT7l)7z_rvB?J)?;wNJ8d-%Gbt$g@hJlKD7khk-&K{>dg z9b8@5esHw1cJ)L{fryg+&m}m!{bKvKy7~u14UPXjs&-QAL=7&@B-`K?Ud?Q3ZL}EqM`n zqUz-o#KeBm%DdWlI@`IRf706iMSJ^S(*7_AXE)-^@^&Z(FFRXBl&dq_p9_aO{A*dn z{w2RtTHAjui}=5!g%E{-{Mg=q*zTVoq7D5R{xV+T!!Pr>R zLT~?bBcY+Drlq63cJ=Bt23mSr1{Q{E*BDs9EG(=nEMQS?5V3KK-V)~H;}gCmAt5R% zA@R@jw@>N->I=X)+3#c|Ab^ybgp8Wxqycyekes$(QQ-W!vuDUiiO^q=)4>&hgp7pj z+&Kzz(u-$E$$l)2lk_q^u+1Y3*Ih?r9H1>(f!Fa*5mA0D?&2E0BrOz=VRWl3D2JK2q5XZ2UIbMhVM;&lq{Ira=d=nX;#fEoR% z7Y|~+d-V~oxgtC)ItB_OQ=38u&eNVUA^VHjL8PJ@6KAwX61z^Pw_TB%j@IBW&GlM@&27WEZt9u6jRb&C9@W zh7nx+KshNXJo6xu#b3<+`v)Z3>0fCA4N+H07iG3M4vS`fyGxmU?cl+~36a@Ub-~TE z=WFiM-+@I+vlZ`m@!5J@4Y+N&o^t*saJFLkxHN85Vd=Le$ui5;=V?a{23zPXIE2UGnFrEcf~&SphgPZX zvpcVueso(BoV)P|Q4p&_5TCXlnhd(nC~F%$xvbjuOC?P#Ic9yS_w*+h{wUHSAAJ1Cuc=%IC8wP?)Oqg@#xM6?HV^tCx7;H8T-UA>BUpx%Nx(#q!b1);Z2s zF4Ip>na4vhixe#lm0(Bq9?_#yn-@D>I3?kXR#;ftb(-d8+G{(LC7no6+QZGu1!-Iw zjKi&rPpvmh1~_wr>WHiN;VrJrUT-xW&-dN7O%t9xpS6YbNlBBpRj{c*Wl7NNc9B30~I-*#k$6cSS3Mnc#1h^=bj8Y

I7}eT-1`e`6Lktz2=ceb_2`~?S{U``o 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 From 1634ea09484e62424842722655c41f0f1183bc55 Mon Sep 17 00:00:00 2001 From: Cesareo <118807053+cesareomacias@users.noreply.github.com> Date: Thu, 13 Feb 2025 09:59:05 +0100 Subject: [PATCH 5/8] Update and rename .spectral.yml to adidas-spectral.yaml -- Included spectral asyncapi rules. -- Updated rules annotations -- Updated custom rules --- .spectral.yml => adidas-spectral.yaml | 76 ++++++--------------------- 1 file changed, 17 insertions(+), 59 deletions(-) rename .spectral.yml => adidas-spectral.yaml (78%) diff --git a/.spectral.yml b/adidas-spectral.yaml similarity index 78% rename from .spectral.yml rename to adidas-spectral.yaml index fc79180..32ba038 100644 --- a/.spectral.yml +++ b/adidas-spectral.yaml @@ -1,13 +1,12 @@ -extends: ["spectral:oas"] +extends: [[spectral:oas, all], [spectral:asyncapi, all]] rules: + operation-tags: off + operation-operationId: off + operation-success-response: error - # --------------------------------------------------------------------------- - # General OAS rules - # --------------------------------------------------------------------------- - - operation-operationId: false - operation-tags: false - operation-2xx-response: error + # ----------------------------# + # Adidas OAS v2.0, v3.0 rules # + # ----------------------------# adidas-paths-kebab-case: description: All YAML/JSON paths MUST follow kebab-case @@ -86,9 +85,9 @@ rules: functionOptions: match: "/^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/" - # --------------------------------------------------------------------------- - # Only OAS2 rules - # --------------------------------------------------------------------------- + # ----------------------# + # Adidas OAS v2.0 rules # + # ----------------------# adidas-oas2-protocol-https-only: description: "ALL requests MUST go through `https` protocol only" @@ -138,18 +137,8 @@ rules: given: "$..parameters..[?(@.in == 'body' && (@.example || @.schema.$ref))]" then: function: truthy - - # example-exists-in-definitions: - # description: All models MUST have a valid example. - # severity: error - # recommended: true - # formats: - # - oas2 - # message: "{{ property }} MUST have a valid example." - # given: "$..definitions..[?(!@.example || !@..$ref)]" - # then: - # function: falsy - # "$..parameters..[?(@.in == 'body')]..[?(@property !== 'properties' && @.example && ( @.type || @.format || @.$ref ))]" + + # example-exists-in-definitions covery by oas2-valid-media-example adidas-oas2-response-success-hal: # schemes and/or produces description: "All success responses MUST be of media type `application/hal+json`" @@ -183,9 +172,9 @@ rules: schema: $ref: "./supermodel/adidas/api/ProblemDetail.yaml" - # --------------------------------------------------------------------------- - # Only OAS3 rules - # --------------------------------------------------------------------------- + # ----------------------# + # Adidas OAS v3.0 rules # + # ----------------------# adidas-oas3-request-support-json: description: Every request MUST support `application/json` media type @@ -198,39 +187,9 @@ rules: then: function: falsy - adidas-oas3-valid-example-in-parameters: - description: Examples must be valid against their defined schema. - message: "{{error}}" - recommended: true - formats: - - oas3 - severity: 0 - type: validation - given: "$..parameters..[?(@.in == 'body')]..[?(@property !== 'properties' && @.example - && ( @.type || @.format || @.$ref ))]" - then: - function: schemaPath - functionOptions: - field: example - schemaPath: "$" + # adidas-oas3-valid-example-in-parameters && adidas-oas3-valid-example-in-definitions covered by oas3-valid-media-example - adidas-oas3-valid-example-in-definitions: - description: Examples must be valid against their defined schema. - message: "{{error}}" - recommended: true - formats: - - oas3 - severity: 0 - type: validation - given: "$..definitions..[?(@property !== 'properties' && @.example && (@.type || - @.format || @.$ref))]" - then: - function: schemaPath - functionOptions: - field: example - schemaPath: "$" - - adidas-oas3-protocol-https-only: # checks how does the servers array values start + adidas-oas3-protocol-https-only: description: "ALL requests MUST go through `https` protocol only" formats: - oas3 @@ -248,7 +207,6 @@ rules: severity: error given: $.paths..responses[?( @property >= 201 && @property < 300 && @property != 204)].content[*]~ recommended: true - # type: "style" formats: - oas3 message: "Response documents MUST be of application/hal+json media types: {{error}}" From 1d2dc988a2a08f88f528e9954673adda0e6b73eb Mon Sep 17 00:00:00 2001 From: Cesareo <118807053+cesareomacias@users.noreply.github.com> Date: Thu, 13 Feb 2025 12:07:12 +0100 Subject: [PATCH 6/8] Update adidas-spectral.yaml Included documentationUrl field --- adidas-spectral.yaml | 1 + 1 file changed, 1 insertion(+) diff --git a/adidas-spectral.yaml b/adidas-spectral.yaml index 32ba038..4438268 100644 --- a/adidas-spectral.yaml +++ b/adidas-spectral.yaml @@ -1,4 +1,5 @@ extends: [[spectral:oas, all], [spectral:asyncapi, all]] +documentationUrl: https://www.example.com/docs/api-style-guide.md rules: operation-tags: off operation-operationId: off From f90b384e427521ab624b619a3be87ee46b49934c Mon Sep 17 00:00:00 2001 From: Cesareo <118807053+cesareomacias@users.noreply.github.com> Date: Thu, 13 Feb 2025 13:26:46 +0100 Subject: [PATCH 7/8] Update adidas-spectral.yaml Typo documentationUrl --- adidas-spectral.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/adidas-spectral.yaml b/adidas-spectral.yaml index 4438268..43df836 100644 --- a/adidas-spectral.yaml +++ b/adidas-spectral.yaml @@ -1,5 +1,5 @@ extends: [[spectral:oas, all], [spectral:asyncapi, all]] -documentationUrl: https://www.example.com/docs/api-style-guide.md +documentationUrl: https://github.com/adidas/api-guidelines/blob/master/ruleset.md rules: operation-tags: off operation-operationId: off From 572a4553207b7c22cad71f027edbdac092a2f140 Mon Sep 17 00:00:00 2001 From: Cesareo <118807053+cesareomacias@users.noreply.github.com> Date: Thu, 13 Feb 2025 16:11:32 +0100 Subject: [PATCH 8/8] Create .spectral.yml Added .spectral.yml in order to don't break existing integrations --- .spectral.yml | 275 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 275 insertions(+) create mode 100644 .spectral.yml diff --git a/.spectral.yml b/.spectral.yml new file mode 100644 index 0000000..03bf495 --- /dev/null +++ b/.spectral.yml @@ -0,0 +1,275 @@ +extends: [[spectral:oas, all], [spectral:asyncapi, all]] +documentationUrl: https://github.com/adidas/api-guidelines/blob/master/ruleset.md +rules: + operation-tags: off + operation-operationId: off + operation-success-response: error + + # ----------------------------# + # Adidas OAS v2.0, v3.0 rules # + # ----------------------------# + + adidas-paths-kebab-case: + description: All YAML/JSON paths MUST follow kebab-case + severity: warn + recommended: true + message: "{{property}} is not kebab-case: {{error}}" + given: $.paths[*]~ + then: + function: pattern + functionOptions: + match: "^\/([a-z0-9]+(-[a-z0-9]+)*)?(\/[a-z0-9]+(-[a-z0-9]+)*|\/{.+})*$" # doesn't allow /asasd{asdas}sadas pattern or not closed braces + + adidas-path-parameters-camelCase-alphanumeric: + description: Path parameters MUST follow camelCase + severity: warn + recommended: true + message: "{{property}} path parameter is not camelCase: {{error}}" + given: $..parameters[?(@.in == 'path')].name + then: + function: pattern + functionOptions: + match: "^[a-z][a-zA-Z0-9]+$" + + adidas-definitions-camelCase-alphanumeric: + description: All YAML/JSON definitions MUST follow fields-camelCase and be ASCII alphanumeric characters or `_` or `$`. + severity: error + recommended: true + message: "{{property}} MUST follow camelCase and be ASCII alphanumeric characters or `_` or `$`." + given: $.definitions[*]~ + then: + function: pattern + functionOptions: + match: "/^[a-z$_]{1}[A-Z09$_]*/" + + adidas-properties-camelCase-alphanumeric: + description: All JSON Schema properties MUST follow fields-camelCase and be ASCII alphanumeric characters or `_` or `$`. + severity: error + recommended: true + message: "{{property}} MUST follow camelCase and be ASCII alphanumeric characters or `_` or `$`." + given: $.definitions..properties[*]~ + then: + function: pattern + functionOptions: + match: "/^[a-z$_]{1}[A-Z09$_]*/" + + adidas-request-GET-no-body: + description: "A 'GET' request MUST NOT accept a 'body` parameter" + severity: error + given: $.paths..get.parameters..in + then: + function: pattern + functionOptions: + notMatch: "/^body$/" + + adidas-headers-no-x-headers: + description: "All 'HTTP' headers SHOULD NOT include 'X-' headers (https://tools.ietf.org/html/rfc6648)." + severity: warn + given: "$..parameters[?(@.in == 'header')].name" + message: "HTTP headers SHOULD NOT include 'X-' prefix." + recommended: true + type: style + then: + function: pattern + functionOptions: + notMatch: "/^(x|X)-/" + + adidas-headers-hyphenated-pascal-case: + description: All `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation + severity: error + given: "$..parameters[?(@.in == 'header')].name" + message: "'HTTP' headers MUST follow 'Hyphenated-Pascal-Case' notation" + recommended: true + type: style + then: + function: pattern + functionOptions: + match: "/^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/" + + # ----------------------# + # Adidas OAS v2.0 rules # + # ----------------------# + + adidas-oas2-protocol-https-only: + description: "ALL requests MUST go through `https` protocol only" + formats: + - oas2 + recommended: true + severity: error + type: "style" + message: "Schemes MUST be https and no other value is allowed." + given: $ + then: + field: schemes + function: schema + functionOptions: + schema: + type: array + items: + type: string + enum: ["https"] + maxItems: 1 + + adidas-oas2-request-support-json: + description: Every request SHOULD support `application/json` media type + formats: + - oas2 + severity: warn + message: "{{description}}: {{error}}" + recommended: true + given: "$..consumes" + then: + function: schema + functionOptions: + schema: + type: array + contains: + type: string + enum: + - application/json + + adidas-oas2-example-exists-in-parameters: + description: All models MUST have a valid example. + severity: error + recommended: true + formats: + - oas2 + message: "{{ property }} MUST have a valid example." + given: "$..parameters..[?(@.in == 'body' && (@.example || @.schema.$ref))]" + then: + function: truthy + + # example-exists-in-definitions covery by oas2-valid-media-example + + adidas-oas2-response-success-hal: # schemes and/or produces + description: "All success responses MUST be of media type `application/hal+json`" + severity: error + given: $.paths..responses[?( @property >= 200 && @property < 300 && @property != 204)] + recommended: true + type: "style" + formats: + - oas2 + message: "Response documents MUST follow application/hal+json: {{error}}" + then: + field: schema + function: schema + functionOptions: + schema: + $ref: "./supermodel/adidas/api/HAL.yaml" + + adidas-oas2-response-error-problem: # schemas and/or produces + description: All error responses MUST be of media type `application/problem+json` + severity: error + formats: + - oas2 + given: $.paths..responses[?( @property >= 400 && @property < 600 )] + recommended: true + type: "style" + message: "Error response document MUST follow application/problem+json: {{error}}" + then: + field: schema.example + function: schema + functionOptions: + schema: + $ref: "./supermodel/adidas/api/ProblemDetail.yaml" + + # ----------------------# + # Adidas OAS v3.0 rules # + # ----------------------# + + adidas-oas3-request-support-json: + description: Every request MUST support `application/json` media type + formats: + - oas3 + recommended: true + severity: error + message: "{{description}}: {{error}}" + given: $.paths.[*].requestBody.content[?(@property.indexOf('json') === -1)]^ + then: + function: falsy + + # adidas-oas3-valid-example-in-parameters && adidas-oas3-valid-example-in-definitions covered by oas3-valid-media-example + + adidas-oas3-protocol-https-only: + description: "ALL requests MUST go through `https` protocol only" + formats: + - oas3 + recommended: true + severity: error + message: "Servers MUST be https and no other protocol is allowed." + given: $.servers..url + then: + function: pattern + functionOptions: + match: "/^https:/" + + adidas-oas3-response-success-hal: + description: "All success responses MUST be of media type `application/hal+json` " + severity: error + given: $.paths..responses[?( @property >= 201 && @property < 300 && @property != 204)].content[*]~ + recommended: true + formats: + - oas3 + message: "Response documents MUST be of application/hal+json media types: {{error}}" + then: + function: enumeration + functionOptions: + values: + - application/hal+json + + # sync and async patterns that can return hal OR problem+json + adidas-oas3-response-success-OK: + description: "All success responses MUST be of media type `application/hal+json` or `application/problem+json`" + severity: error + given: $.paths..responses[?( @property == 200 )].content[*]~ + recommended: true + formats: + - oas3 + message: "Response documents MUST be of application/hal+json or application/problem+json media types: {{error}}" + then: + function: enumeration + functionOptions: + values: + - application/hal+json + - application/problem+json + + adidas-oas3-response-success-hal-body: # schemes and/or produces + description: "All success responses MUST follow `application/hal+json` schema" + severity: error + given: $.paths..responses[?( @property == 200 && @property < 300 && @property != 204)].content[?(@property === "application/hal+json")] + recommended: true + type: "style" + formats: + - oas3 + message: "Response documents MUST follow application/hal+json schema: {{error}}" + then: + field: schema + function: schema + functionOptions: + schema: + $ref: "./supermodel/adidas/api/HAL.yaml" + + + # --------------------------------------------------------------------------- + # Not implemented + # --------------------------------------------------------------------------- + + # --------------------------------------------------------------------------- + # Other rules which are redundant or not feasible + # --------------------------------------------------------------------------- + + # fields-date-iso8601: + # description: Date and time MUST follow [`ISO 8601` standard](https://www.iso.org/iso-8601-date-and-time-format.html) + # severity: error + # fields-language-iso639: + # description: Language codes MUST follow [`ISO 639` standard](https://www.iso.org/iso-639-language-codes.html) + # severity: error + # fields-country-iso3166: + # description: Country codes MUST follow [`ISO 3166 alpha-2` standard](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) + # severity: error + # fields-currency-iso4217: + # description: Currency codes MUST follow [`ISO 4217` standard](https://en.wikipedia.org/wiki/ISO_4217) + # severity: error + # response-303-async-link-header: + # description: A successful and finished async api request returns `303` response code and sends the target resource location in the `Link` header + # severity: hint