James Higginbotham, Executive API Consultant, shares his API and product release insights with a list of 10 essential steps to improve the next release of your API.
If you're interested in being a part of our next series, fill out this short form and we'll get in touch with you for our next run.
It is exciting to release something new. The thrill of seeing an idea to completion is always an exciting time for software teams. But how do you know when an API is ready to release? What if you missed something that could result in increased support emails and calls? What if you broke existing internal or 3rd-party integrations?
This article provides a 10-point checklist to help ensure your next API release is as smooth as possible.
1. Did you verify that we met stakeholder needs?
You may design the most beautiful, amazing API ever imagined. It might cause API designers to weep at its beauty. But, if it doesn't solve the problems of your stakeholders, you have failed to deliver a well-designed and useful API.
To avoid this problem, I recommend a design-first approach. This approach first identifies the capabilities to be delivered, then moves toward an API design to meet those capabilities. Once designed, the API design is then captured in the OpenAPI Specification format and delivered quickly to internal teams and trusted stakeholders for review and feedback. This is the time when API design changes are the cheapest to make, as no code has been built yet. Use this time to ensure you are solving the right problem.
In my API consulting engagements, I see this problem occur more often than you may think. Some organizations fail to see the transformative nature of APIs, treating them more like a library or framework by isolating their impact to IT alone. Organizations that view APIs as strategic and transformative to the business will take a design-first approach. The result is the creation of digital assets that offer reuse and accelerated time-to-market.
Once your team has implemented some or all of endpoints that are part of the release, you should then offer a preview release to your trusted stakeholders. It is during this preview release that you can gain additional feedback and make necessary changes before officially releasing your API. Use this time to work out trouble spots, improve documentation, and expand code examples that demonstrate API usage (as we'll discuss below). While it isn't cheap to make changes at this point as it was in the design stage, it is still easier than after your API has been officially released.
Once your API has been officially released and integrated with your first stakeholder, your API design is forever. You can add new endpoints and maybe new fields to existing endpoint representations, but renaming or modifying existing endpoints will break existing API consumers, leading to upset customers and perhaps customer churn.
2. Did any updates result in a breaking change to your API?
It is important to recognize the negative impact that a new API version can have on your consumers. When you create a new version of an API, you are telling your API consumers that they have to do some work to continue working with you. Code needs to be changed, and integrations need to be retested. While your API re-design makes you happy, the changes required becomes your consumers' problem - every consumer.
Remember, your API design is the contract you are establishing between you, as the API provider, and your consumers. Therefore, it is urgent that you identify any breaking changes to your API early. That is why I recommend taking a design-first, rather than code-first, approach to API releases as I mentioned above. By focusing first on the API design, you can review and identify breaking changes early and seek to resolve the break by another means (when possible).
If you are required to make breaking changes, you need to determine the impact of those changes. Review your API dashboard (you do have the right management tools that can help with this, right?). Determine who, if anyone, may be impacted. If an API endpoint has been used for some time, you may need to consider rolling out new endpoint(s) to offer the changed functionality rather than modifying existing ones. The sooner you catch breaking changes, the sooner they can be resolved in some way.
3. Did you perform a thorough security review?
Don’t assume your API was designed to be used outside of the original use case - most never are. Time constraints cause us to take shortcuts and make assumptions. Take the time to review every new or updated endpoint in your release to ensure that the data being returned is appropriate for your API consumers, both internal and external to your organization.
This is especially critical if your API interacts with sensitive data, such as personally identifiable information (PII) or non-public information (NPI). This kind of data often must implement additional protection from improper use. As a result of the updated GDPR rules in Europe and the associated steep fines when violated, this is a crucial step that must never be skipped due to constrained time or budget.
I have found that organizations who integrate security reviews as part of their API delivery process are more likely to catch these security issues before a release, reducing the likelihood of exposing sensitive data. Organizations that choose not to take this step, perhaps under the misguided idea of being "agile" or need for speed-to-market, will spend more time patching issues post-release.
4. Is your API documentation up-to-date, including code examples?
Poor documentation (or none at all) can lead to confusion by developers that will be integrating your API. When releasing a new revision of your API, make sure your documentation remains clear and relevant. Verify that your endpoint reference documentation, often generated from your OpenAPI Specification (OAS), has been reviewed. Document clearly what problem each endpoint is trying to solve, as well as what it isn’t trying to solve.
Additionally, add or update your code examples. These examples may use a combination of cURL and/or code snippets for the top 3-5 programming languages of your target audience. At a minimum, they should demonstrate how to accomplish simple tasks based on your API capabilities. Keith Casey wrote a great post titled, ”The Three Styles of API Documentation”, if you are still working on your approach to documentation.
More complex examples and workflows may be demonstrated using small demo apps, allowing developers to gain a deeper understanding of how to connect API calls together to tackle larger solutions. Offer these apps via GitHub for easy access.
Remember: Be sure your API documentation answers the kinds of questions raised by those outside of your immediate dev team. Don't assume that just because an endpoint is obvious to you, everyone else will understand how it works.
5. Have you captured new or updated capabilities into a changelog?
New releases should include a published changelog - a quick reference for what has been added or enhanced. Don't expose implementation details, such as internal services or database schema changes. However, do be clear on what changes impact your API consumers. Often, a changelog can be verified against actual changes by reviewing new/modified code, documentation, and examples. Spend the time to craft a clear post and/or email with a list of what has changed and why these changes may be important for your stakeholders.
6. Have you updated your API management layer configuration?
API gateways and API management layers provide a bridge between your code and your API consumers. While your configuration may proxy all authorized calls to your backend API, some endpoints may require additional security or fine-grained access control. Be sure to update your gateway or management layer with any new URLs and associated security rules and rate limits.
When possible, I encourage organizations to automate this process as part of your CI/CD automation. That will avoid outages due to misconfigurations during the release process. Most gateways and management layers offer internal management APIs that can be used to register new endpoints and apply security rules in an automated way, perhaps driven by your OpenAPI Specification.
7. Have you updated your KPI dashboard and usage reports?
With new endpoints come the possibility for new metrics. Once you release your API, you will need to ensure that it continues to meet your business and operational goals. Many API gateways and management layers offer analytics support. These metrics can be used to assess your key performance indicators (KPIs) that business stakeholders use to measure API program success. If you are uncertain what metrics are most important to track, check out the Apigee article titled, "KPIs for APIs: 12 Key Metrics for API Programs".
Review the changes from your changelog to determine if your KPI dashboard should be updated. Are there new metrics that you need to track regarding business goals or new kinds of transactions? Are your usage reports updated to include these new endpoints? What do your executives, product managers, business development, marketing, and sales teams need to track as a result of this new release? Don't miss this opportunity to start tracking these new metrics immediately after release.
8. Has your API been thoroughly tested?
Releasing an API without tests is very risky. So, teams often surround their code with unit tests and perhaps some functional tests that ensure each API endpoint is functioning properly and handles error cases as expected. That is the minimum level of testing required before releasing an API.
If you haven't already, consider adding acceptance testing to your test strategy. Acceptance testing, also called solution-oriented testing, ensures that the API as a whole supports the intended use cases that it was designed to solve. In my opinion, acceptance testing is the most valuable testing approach for an API. It looks for both correctness and that the API can support intended usage.
9. Does your API release match your published design contract?
API contracts are typically defined prior to implementation when applying a design-first approach. These contracts should be verified as part of the functional testing process to ensure the implementation reflects the design. The most common contract specification format is OpenAPI Specification (formally known as Swagger). By using automated tests that verify your API contract against the release, you can be sure that the implementation matches the design. This will prevent developer confusion by a design that doesn't match the actual behavior of your API.
10. Has a blog post been scheduled to announce the new release?
Finally, be sure to draft a post to announce the new release. Include the changelog, mentioned earlier, along with other important details about the release. Even if your API is internal and only targets internal teams, it is important to have a communication channel to keep your audience updated. Announcements often generate interest, excitement, and the understanding that your API is under active improvement rather than becoming stagnant.
Most teams have a release checklist that they use to verify their product release. Teams must also consider the API as part of that release as well. Incorporate these ten points into your release process to ensure customers and internal developers have a great experience with their API integration.