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