Mirrors/api-guidelines
1
0
Fork 0
mirror of https://github.com/adidas/api-guidelines.git synced 2025-10-24 15:19:17 +00:00
Code Issues Packages Projects Releases Wiki Activity

GITBOOK-1: No subject

Browse Source
This commit is contained in:
Cesareo Macias
2025-02-12 16:37:20 +00:00
committed by gitbook-bot
parent 1b52a38e90
commit a6d7fc63de
4 changed files with 53 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
.gitbook/assets/adidas_company_logo_BWp.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.3 KiB

BIN
.gitbook/assets/adidas_company_logo_BWr.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 3.0 KiB

54
README.md
View File

@@ -1,6 +1,8 @@
# adidas API Guidelines
![adidas logo](adidaslogo.jpg)
<figure><picture><source srcset=".gitbook/assets/adidas_company_logo_BWr.png" media="(prefers-color-scheme: dark)"><img src=".gitbook/assets/adidas_company_logo_BWp.png" alt=""></picture><figcaption></figcaption></figure>
[![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.&#x20;
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 <oas-file> -r <adidas-api-guidelines-folder>/.spectral.yaml` where `<adidas-api-guidelines-folder>/.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 <api-specification-file> --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
&#x20;_**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)

50
rest-api-guidelines/guides/api-testing-ci-environment.md
View File

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