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

GitBook: [master] 102 pages and one asset modified

Browse Source
This commit is contained in:
apidesigner
2018-07-23 07:49:01 +00:00
committed by gitbook-bot
parent af88d15fd0
commit 3b81882249
68 changed files with 850 additions and 712 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
rest-api-guidelines/guides/README.md Normal file
View File

@@ -0,0 +1,11 @@
# Guides
API-related guides:
* [API Design Process](https://tools.adidas-group.com/confluence/display/EA/API+Design+Process)
* Migration of Legacy Services \(SOAP\)
* API Testing with Dredd
* Continuous Integration / Deployment / Delivery
* [Apiary](https://help.apiary.io/api_101/understanding-apiary/)
* API Management

102
rest-api-guidelines/guides/api-testing-ci-environment.md Normal file
View File

@@ -0,0 +1,102 @@
# 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\).
## Environment Prerequisites
The following must be available in the CI environment before testing:
1. **Node.js** runtime MUST be available in the CI environment:
```text
$ node -v
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
$ npm install -g dredd --no-optional
```
```text
$ dredd --version
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
```text
$ 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. 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
$ export API_HOST=http://deheremap7336.emea.adsint.biz:8004`
```
### 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:
```text
$ dredd swagger.yaml $API_HOST -r apiary
```
> See [Dredd Command-line Interface](https://dredd.readthedocs.io/en/latest/usage-cli/).
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\) as well as in Apiary.

112
rest-api-guidelines/guides/complete-api-development.md Normal file
View File

@@ -0,0 +1,112 @@
# Complete API Development
1. **Design the API**
1. Analyze business requirements
2. Identify affordances
> e.g.: Create user, Submit order, Search for an article
3. Identify resources
> e.g.: User, Order, Article
4. Identify relations
> e.g.: User has many Orders via order relation, all of the required affordances should be mapped to relations.
5. Formalize the design in the [Open API Specification](http://swagger.io/specification/) \(OAS, formerly known as "Swagger"\) format
6. Follow the [adidas API guidelines](https://adidas-group.gitbooks.io/api-guidelines/content/)
7. Put the OAS file into [Apiary adidas group](https://apiary.io)
8. Make sure the OAS file passes all adidas API Apiary style guide checks
9. Verify the design using Apiary Documentation and Apiary Mock Service
10. Review the API Design
11. Put the OAS file in a version control system \(VCS\) repository
12. Set up a CD pipeline to push OAS file from VCS to Apiary, whenever the file is changed
2. **Develop the API**
1. Check out the VCS repository with the OAS file
2. Set up the [Dredd API testing tool](https://github.com/apiaryio/dredd) locally
3. Configure the Dredd for your project
```text
$ dredd init
```
4. Run the Dredd test locally
> Against locally running API implementation, Every test should fail.
5. Implement the API
> Keep running the Dredd locally to see the progress.
6. Set up a [CI/CD pipeline](https://adidas-group.gitbooks.io/api-guidelines/content/guides/api-testing-ci-environment.html) to execute the Dredd tests automatically
> NOTE: Both TeamCity and Jenkins environments are available, contact adidas API evangelist for details.
3. **Deploy the API**
1. Deploy the service
2. Update the OAS file to add the deployment HOST
> ```text
> host: adidas.api.mashery.com
> basePath: /demo-approval-api
> ```
3. Verify the deployment with Dredd
> Use Dredd pointed towards the deployment host, be careful NOT to run it against the production OR using real production credentials.
4. Monitor the API usage "From performance and technical standpoint."
4. **Expose the API using Mashery**
1. **API**
1. Create new API Definition in Mashery
2. Create a new API Endpoint the API Definition
> Set the "Your Endpoint Address" to the internal deployment HOST.
3. Create a new API Package in Mashery
4. Create a new API Plan within the API Package
5. Use Mashery API Designer to add the newly created API Definitions' API Endpoint to the API Plan
6. Revisit the API Plan's API key default settings
7. Revisit the API Plan's API default rate limits
8. Revisit the API Plan's access policy/authorization
9. **API Documentation**
1. Create new adidas API developer's portal page in the Mashery
> Manage > Content > Documentation > APIs
2. [Embed Apiary documentation](https://help.apiary.io/tools/embed/#apiary-embed-api-reference) on the newly created API Page
3. Revisit the API documentation access policy/authorization
5. **Use the API**
> This step can be done at the same time as "Develop the API" thank Apiary hosted Mock, Inspector, and Documentation.
1. Read API documentation at Apiary
2. Use API mock service provided by Apiary
3. Use API call inspector provided by Apiary
4. Obtain your API key
> The key is part of the API Plan created in Mashery and can be requested from your dashboard in the adidas API developer's portal.
5. When available use API implementation via Apiary proxy to debug the API calls
6. Use production deployment
6. **Analyze the API**
1. Examine the use of production API Using Mashery
2. Analyze the technical performance metrics
3. Collect the feedback from users
7. **Update API Design**
> Based on the analysis, new or changing business requirements
1. Create a new branch in the VCS repository with OAS file
2. Create a new project \(alternative\) in Apiary
3. Make sure the CI/CD pipeline is:
1. Set to push the OAS file to Apiary but make sure to modify the Apiary project name
2. Set to run Dredd test in the CI/CD
4. Modify the design \(OAS file\) accordingly, follow the "Design API" step
5. Follow the [**rules for extending**](https://adidas-group.gitbooks.io/api-guidelines/content/core-principles/rules-for-extending.html) and [**adidas API guidelines versioning policies**](https://adidas-group.gitbooks.io/api-guidelines/content/evolution/versioning.html)
6. Use VCS pull request \(PR\) to propose the change to review
7. After the API Design change is verified, reviewed and approved, continue with the "Develop the API" phase
8. Eventually, when the updated design is ready to be deployed for production, merge the branch into the production branch
9. Follow this guide from "Expose the API using Mashery" step