From 62601ea5d26f9d51427605f4885cb951d0daf0e4 Mon Sep 17 00:00:00 2001 From: Zdenek Nemec Date: Fri, 17 Jan 2020 08:14:30 +0100 Subject: [PATCH] Replace apiary with swaggerhub --- SUMMARY.md | 2 +- examples/valid/demo-orderapi-v3.oas2.yaml | 3 - rest-api-guidelines/core-principles/apiary.md | 12 ---- .../core-principles/design-platform.md | 12 ++++ .../core-principles/openapi-specification.md | 2 +- .../core-principles/testing.md | 2 +- rest-api-guidelines/evolution/versioning.md | 7 --- rest-api-guidelines/guides/README.md | 1 - .../guides/api-testing-ci-environment.md | 55 ++----------------- .../guides/complete-api-development.md | 2 + rest/examples.md | 19 +------ rest/execution/authentication.md | 1 - 12 files changed, 24 insertions(+), 94 deletions(-) delete mode 100644 rest-api-guidelines/core-principles/apiary.md create mode 100644 rest-api-guidelines/core-principles/design-platform.md diff --git a/SUMMARY.md b/SUMMARY.md index 7be3c21..d1d03b5 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -19,7 +19,7 @@ * [Introduction](rest-api-guidelines/rest.md) * [Core Principles](rest-api-guidelines/core-principles/README.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) * [Testing](rest-api-guidelines/core-principles/testing.md) * [Protocol](rest-api-guidelines/protocol/README.md) diff --git a/examples/valid/demo-orderapi-v3.oas2.yaml b/examples/valid/demo-orderapi-v3.oas2.yaml index 1dab834..3c99ffb 100644 --- a/examples/valid/demo-orderapi-v3.oas2.yaml +++ b/examples/valid/demo-orderapi-v3.oas2.yaml @@ -7,9 +7,6 @@ info: email: "z@goodapi.co" description: | 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: - application/hal+json # Representation message format diff --git a/rest-api-guidelines/core-principles/apiary.md b/rest-api-guidelines/core-principles/apiary.md deleted file mode 100644 index bb5c57d..0000000 --- a/rest-api-guidelines/core-principles/apiary.md +++ /dev/null @@ -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. - diff --git a/rest-api-guidelines/core-principles/design-platform.md b/rest-api-guidelines/core-principles/design-platform.md new file mode 100644 index 0000000..73c33cc --- /dev/null +++ b/rest-api-guidelines/core-principles/design-platform.md @@ -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). + diff --git a/rest-api-guidelines/core-principles/openapi-specification.md b/rest-api-guidelines/core-principles/openapi-specification.md index ee09779..f820c39 100644 --- a/rest-api-guidelines/core-principles/openapi-specification.md +++ b/rest-api-guidelines/core-principles/openapi-specification.md @@ -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 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 diff --git a/rest-api-guidelines/core-principles/testing.md b/rest-api-guidelines/core-principles/testing.md index 3a8a172..631e1c2 100644 --- a/rest-api-guidelines/core-principles/testing.md +++ b/rest-api-guidelines/core-principles/testing.md @@ -2,7 +2,7 @@ ## 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. diff --git a/rest-api-guidelines/evolution/versioning.md b/rest-api-guidelines/evolution/versioning.md index 9a1073f..3d4c4cd 100644 --- a/rest-api-guidelines/evolution/versioning.md +++ b/rest-api-guidelines/evolution/versioning.md @@ -87,13 +87,6 @@ info: 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 * [Evolving HTTP APIs](https://www.mnot.net/blog/2012/12/04/api-evolution) diff --git a/rest-api-guidelines/guides/README.md b/rest-api-guidelines/guides/README.md index a77d3e0..150d643 100644 --- a/rest-api-guidelines/guides/README.md +++ b/rest-api-guidelines/guides/README.md @@ -6,6 +6,5 @@ API-related guides: * Migration of Legacy Services \(SOAP\) * API Testing with Dredd * Continuous Integration / Deployment / Delivery -* [Apiary](https://help.apiary.io/api_101/understanding-apiary/) * API Management diff --git a/rest-api-guidelines/guides/api-testing-ci-environment.md b/rest-api-guidelines/guides/api-testing-ci-environment.md index c91e5a4..f2c2b1e 100644 --- a/rest-api-guidelines/guides/api-testing-ci-environment.md +++ b/rest-api-guidelines/guides/api-testing-ci-environment.md @@ -13,13 +13,6 @@ The following must be available in the CI environment before testing: 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: ```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) ``` -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 ### Test Run Prerequisites 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 - $ export APIARY_API_NAME=bomapi3 - ``` + The file should be fetched from [API Design Platform](design-plaform.md) - > See [How to find the Apiary API name](https://help.apiary.io/faq/find-api-name/) for more details. - -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 +2. The host \(address\) of the service being tested ```text $ 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 -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 -$ 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/). @@ -98,5 +56,4 @@ The Dredd will perform the tests and exits usually if the tests have passed. You $ 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\) diff --git a/rest-api-guidelines/guides/complete-api-development.md b/rest-api-guidelines/guides/complete-api-development.md index 63ac3b4..0636947 100644 --- a/rest-api-guidelines/guides/complete-api-development.md +++ b/rest-api-guidelines/guides/complete-api-development.md @@ -1,5 +1,7 @@ # 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. Analyze business requirements 2. Identify affordances diff --git a/rest/examples.md b/rest/examples.md index c46b5c1..c481b51 100644 --- a/rest/examples.md +++ b/rest/examples.md @@ -1,20 +1,3 @@ # Examples -Sample APIs following the guidelines are available at [adidas-group GitHub](https://github.com/adidas-group). The samples include the following: - - -### [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. - +Sample APIs following the guidelines are available at in the [examples repository folder](https://github.com/adidas/api-guidelines/tree/master/examples). diff --git a/rest/execution/authentication.md b/rest/execution/authentication.md index f042197..05bf868 100644 --- a/rest/execution/authentication.md +++ b/rest/execution/authentication.md @@ -22,4 +22,3 @@ Adidas-API-Key: 9kfapap6612jkfd3ja9323q Host: adidas.api.mashery.com ``` -> NOTE: See more details in the [[Demo] Approval API](http://docs.demoapprovalapi.apiary.io) example.