Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/adidas/api-guidelines

adidas group API design guidelines
https://github.com/adidas/api-guidelines

adidas adidas-group api architecture asynchronous guidelines http kafka openapi protocol rest rest-api

Last synced: 3 days ago
JSON representation

adidas group API design guidelines

Host: GitHub
URL: https://github.com/adidas/api-guidelines
Owner: adidas
License: mit
Created: 2017-01-18T14:00:34.000Z (almost 8 years ago)
Default Branch: master
Last Pushed: 2024-06-19T10:06:09.000Z (5 months ago)
Last Synced: 2024-08-29T00:03:18.597Z (2 months ago)
Topics: adidas, adidas-group, api, architecture, asynchronous, guidelines, http, kafka, openapi, protocol, rest, rest-api
Homepage: https://adidas.gitbook.io/api-guidelines/
Size: 1.37 MB
Stars: 281
Watchers: 26
Forks: 92
Open Issues: 6
Metadata Files:
- Readme: README.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE
- Code of conduct: .github/CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

# adidas API Guidelines

![adidas logo](adidaslogo.jpg)

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[Read online at GitBook](https://adidas.gitbook.io/api-guidelines/)

### 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.

These guidelines lay down the foundation for collaboration, stability, and extensibility.

### Guidelines

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)

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

The CAPITALIZED words throughout these guidelines have a special meaning:

> ```
> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
> "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
> this document are to be interpreted as described in RFC2119.
> ```

Refer to [RFC2119](https://www.ietf.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/).

To install Spectral you will need Node.js and a package manager (npm or yarn).

Note: The version used with the spectral specifications was 5.3.0

```
npm install -g @stoplight/[email protected]

# OR

yarn global add @stoplight/[email protected]
```

Once installed, to verify your OAS file with spectral execute `spectral lint -r /.spectral.yaml` where `/.spectral.yaml` indicated the location `.spectral.yaml` file.

For further documentation on Spectral refer to their [documentation](https://stoplight.io/p/docs/gh/stoplightio/spectral/README.md).

### Questions & Comments

_Please contact_ [[email protected]_](mailto:[email protected]) _in case of questions._

## 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.

## Last Review

May 2024

## License and Software Information

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 [email protected]_.

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)