The Complete API Development Guide
Design the API
Analyze business requirements
e.g.: Create user, Submit order, Search for an article
e.g.: User, Order, Article
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 execute the Dredd tests automatically
NOTE: Both TeamCity and Jenkins environments 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 NOT to run it against the production OR using real production credentials.
Monitor the API usage "From performance and technical standpoint."
Expose the API using Mashery
Create new API Definition in Mashery
Create a new API Endpoint the API Definition
Set the "Your Endpoint Address" to the internal deployment HOST.
Create a new API Package in Mashery
Create a new API Plan within the API Package
Use Mashery API Designer to add the newly created API Definitions' API Endpoint to the API Plan
Revisit the API Plan's API key default settings
Revisit the API Plan's API default rate limits
Revisit the API Plan's access policy/authorization
Create new adidas API developer's portal page in the Mashery
Manage > Content > Documentation > APIs
Embed Apiary documentation on the newly created API Page
Revisit the API documentation access policy/authorization
Use the API
This step can be done at the same time as "Develop the API" thank 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
Examine 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:
Set to push the OAS file to Apiary but make sure to modify the Apiary project name
Set to run Dredd test in the CI/CD
Modify the design (OAS file) accordingly, follow the "Design API" step
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 into the production branch
Follow this guide from "Expose the API using Mashery" step