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

Replace apiary with swaggerhub

Browse Source
This commit is contained in:
Zdenek Nemec
2020-01-17 08:14:30 +01:00
parent 740980ea43
commit 62601ea5d2
12 changed files with 24 additions and 94 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
SUMMARY.md
View File

@@ -19,7 +19,7 @@
* [Introduction](rest-api-guidelines/rest.md) * [Introduction](rest-api-guidelines/rest.md)
* [Core Principles](rest-api-guidelines/core-principles/README.md) * [Core Principles](rest-api-guidelines/core-principles/README.md)
* [OpenAPI Specification](rest-api-guidelines/core-principles/openapi-specification.md) * [OpenAPI Specification](rest-api-guidelines/core-principles/openapi-specification.md)
* [API Design Platform](rest-api-guidelines/core-principles/apiary.md) * [API Design Platform](rest-api-guidelines/core-principles/design-platform.md)
* [Design Maturity](rest-api-guidelines/core-principles/design-maturity.md) * [Design Maturity](rest-api-guidelines/core-principles/design-maturity.md)
* [Testing](rest-api-guidelines/core-principles/testing.md) * [Testing](rest-api-guidelines/core-principles/testing.md)
* [Protocol](rest-api-guidelines/protocol/README.md) * [Protocol](rest-api-guidelines/protocol/README.md)

3
examples/valid/demo-orderapi-v3.oas2.yaml
View File

@@ -7,9 +7,6 @@ info:
email: "z@goodapi.co" email: "z@goodapi.co"
description: | description: |
Sample API conforming to [adidas API Guidelines](https://adidas.gitbook.io/api-guidelines/). Sample API conforming to [adidas API Guidelines](https://adidas.gitbook.io/api-guidelines/).
This API is [documented at Apiary](http://docs.demotemplate.apiary.io)
and stored on GitHub.
produces: produces:
- application/hal+json # Representation message format - application/hal+json # Representation message format

12
rest-api-guidelines/core-principles/apiary.md
View File

@@ -1,12 +0,0 @@
# API Design Platform
1. [Apiary](https://apiary.io/) is the primary platform supporting [API first approach](../../general-guidelines/api-first.md). Apiary **MUST** be used during API Design.
2. Every API description **MUST** be stored in [Apiary](https://apiary.io/) under the ADIDAS team.
3. Apiary **MUST** be the **single source of truth** to learn about existing APIs within the organization.
> NOTE: Apiary supports API-first approach in multiple ways:
> a. Validates API description for correctness and automatically generates API documentation to drive the discussion between stakeholders. \(No more emails with API description flying between stakeholders\)
>
> NOTE: The synchronization between the version control system and adidas [API Description platform](apiary.md)
> should be automated using CI/CD framework.

12
rest-api-guidelines/core-principles/design-platform.md Normal file
View File

@@ -0,0 +1,12 @@
# API Design Platform
1. [SwaggerHub](https://swageri.io/) is the primary platform supporting [API first approach](../../general-guidelines/api-first.md). SwaggerHub **SHOULD** be used during API Design.
2. Every API description **MUST** be stored in [SwaggerHub](https://http://design.api.3stripes.io/) under the adidas team.
3. SwaggerHub **MUST** be the **single source of truth** to learn about existing APIs within the organization.
> NOTE: SwaggerHub supports API-first approach in multiple ways:
> For example, it validates API description for correctness and automatically generates API documentation to drive the discussion between stakeholders. \(No more emails with API description flying between stakeholders\)
>
> NOTE: The synchronization between the version control system and adidas API Design platform
> should be automated (e.g. using CI/CD framework or the Design Platform capabilities).

2
rest-api-guidelines/core-principles/openapi-specification.md
View File

@@ -2,7 +2,7 @@
Every API **MUST** be described using an 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). Every API **MUST** be described using an 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).
Every API description **MUST** be published in adidas [API design platform](apiary.md) and it **SHOULD** be stored in version control system \(Bitbucket, GitHub\) in the same repository as the API implementation. Every API description **MUST** be published in adidas [API design platform](design-platform.md) and it **SHOULD** be stored in version control system \(Bitbucket, GitHub\) in the same repository as the API implementation.
## Language ## Language

2
rest-api-guidelines/core-principles/testing.md
View File

@@ -2,7 +2,7 @@
## DREDD ## 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/). 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).
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. 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.

7
rest-api-guidelines/evolution/versioning.md
View File

@@ -87,13 +87,6 @@ info:
Has MAJOR version 2, MINOR version 1 and PATCH version 3. Has MAJOR version 2, MINOR version 1 and PATCH version 3.
#### Demo
API description \(OAS2\) files demonstrating a proposal of an backward-incompatible change turned into a backward compatible change are available at [Bitbucket \(diff\) ](https://bitbucket.org/apidesigner/demo-versioning-api/pull-requests/1/add-name-parameter/diff)and documented in Apiary:
* [Production version](https://demoversioningproduction.docs.apiary.io/#) as being consumed by clients
* [Development version](https://demoversioningdevelopment.docs.apiary.io/#) proposing a backward incompatible change
#### Recommended Reading #### Recommended Reading
* [Evolving HTTP APIs](https://www.mnot.net/blog/2012/12/04/api-evolution) * [Evolving HTTP APIs](https://www.mnot.net/blog/2012/12/04/api-evolution)

1
rest-api-guidelines/guides/README.md
View File

@@ -6,6 +6,5 @@ API-related guides:
* Migration of Legacy Services \(SOAP\) * Migration of Legacy Services \(SOAP\)
* API Testing with Dredd * API Testing with Dredd
* Continuous Integration / Deployment / Delivery * Continuous Integration / Deployment / Delivery
* [Apiary](https://help.apiary.io/api_101/understanding-apiary/)
* API Management * API Management

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

@@ -13,13 +13,6 @@ The following must be available in the CI environment before testing:
v7.5.0 v7.5.0
``` ```
2. **Ruby** runtime MUST be available in the CI environment:
```text
$ ruby -v
ruby 2.4.0p0 (2016-12-24 revision 57164) [x86_64-darwin16]
```
3. [**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:
```text ```text
@@ -31,52 +24,17 @@ The following must be available in the CI environment before testing:
dredd v2.2.5 (Darwin 16.4.0; x64) dredd v2.2.5 (Darwin 16.4.0; x64)
``` ```
4. [**Apiary CLI Tool**](https://help.apiary.io/tools/apiary-cli) MUST be installed globally in the CI environment:
```text
$ gem install apiaryio
```
```text
$ apiary version
0.8.0
```
5. **Apiary API Key** MUST be set in the CI Environment environment variables:
```text
$ export APIARY_API_KEY=xyz
```
To obtain an Apiary API key, head to [https://login.apiary.io/tokens](https://login.apiary.io/tokens) \(NOTE: You will need the "ALL" Scope\)
## Testing an API ## Testing an API
### Test Run Prerequisites ### Test Run Prerequisites
To test an API within the CI environment provisioned as mentioned in the environment prerequisites, you will need the following: To test an API within the CI environment provisioned as mentioned in the environment prerequisites, you will need the following:
1. The name \(subdomain\) of API project at Apiary 1. A `swagger.yaml` file with the description of API being tested
```text The file should be fetched from [API Design Platform](design-plaform.md)
$ export APIARY_API_NAME=bomapi3
```
> See [How to find the Apiary API name](https://help.apiary.io/faq/find-api-name/) for more details. 2. The host \(address\) of the service being tested
2. A `swagger.yaml` file with the description of API being tested
To fetch the swagger.yaml file from Apiary run the following command before the test:
```text
$ apiary fetch --api-name=$APIARY_API_NAME --output="swagger.yaml"
```
The swagger document for Apiary project `bomapi3` was saved as local file `./swagger.yaml`.
> See [Fetching Published Documentation](https://help.apiary.io/tools/apiary-cli/#fetching-published-documentation).
3. The host \(address\) of the service being tested
```text ```text
$ export API_HOST=http://deheremap7336.emea.adsint.biz:8004` $ export API_HOST=http://deheremap7336.emea.adsint.biz:8004`
@@ -84,10 +42,10 @@ To test an API within the CI environment provisioned as mentioned in the environ
### Running the Test ### Running the Test
With all of the above \(`APIARY_API_KEY`, `APIARY_API_NAME`, `API_HOST`, set up and `swagger.yaml` file present in the current directory\), run: Run:
```text ```text
$ dredd swagger.yaml $API_HOST -r apiary $ dredd swagger.yaml $API_HOST
``` ```
> See [Dredd Command-line Interface](https://dredd.readthedocs.io/en/latest/usage-cli/). > See [Dredd Command-line Interface](https://dredd.readthedocs.io/en/latest/usage-cli/).
@@ -98,5 +56,4 @@ The Dredd will perform the tests and exits usually if the tests have passed. You
$ echo $? $ echo $?
``` ```
Everything else but `0` should break the build. The test results will be visible in the CLI \(log\) as well as in Apiary. Everything else but `0` should break the build. The test results will be visible in the CLI \(log\)

2
rest-api-guidelines/guides/complete-api-development.md
View File

@@ -1,5 +1,7 @@
# Complete API Development # Complete API Development
> NOTE: The content of this file is outdated, refering to previous technologies used at adidas. It is kept for reference until its refresh
1. **Design the API** 1. **Design the API**
1. Analyze business requirements 1. Analyze business requirements
2. Identify affordances 2. Identify affordances

19
rest/examples.md
View File

@@ -1,20 +1,3 @@
# Examples # Examples
Sample APIs following the guidelines are available at [adidas-group GitHub](https://github.com/adidas-group). The samples include the following: Sample APIs following the guidelines are available at in the [examples repository folder](https://github.com/adidas/api-guidelines/tree/master/examples).
### [Simple API](https://github.com/adidas-group/demo-simple-api)
Very simple API including implementation, testing, and full CI/CD lifecycle.
### [Approval API](https://github.com/adidas-group/demo-approval-api)
Real-world API with state transition, API key client app authentication, exposed via API management.
### [Orders API](https://github.com/adidas-group/demo-orders-api)
Sample API used as the template for newly created projects at Apiary.
### [Appointment Service](https://github.com/adidas-group/demo-appointment-service)
Demo API, including implementation and testing used during training.
### [Complex Search Parameters](https://github.com/adidas-group/demo-complex-search)
Sample API showcasing description of complex query parameter rules.

1
rest/execution/authentication.md
View File

@@ -22,4 +22,3 @@ Adidas-API-Key: 9kfapap6612jkfd3ja9323q
Host: adidas.api.mashery.com Host: adidas.api.mashery.com
``` ```
> NOTE: See more details in the [[Demo] Approval API](http://docs.demoapprovalapi.apiary.io) example.