It is time to release your API into production. But, how do you know when an API is ready to release? What if you missed something that could result in increased support or downtime? This article outlines a checklist of 10 things to check before your next API release.
1. Verify the API meets stakeholder needs
Once your API has been officially released and integrated with your first stakeholder, your API design is forever. You can add new endpoints and perhaps 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. Getting it right the first time is important.
In my API consulting engagements, I see this problem occur more often than you may think. Some organisations assume that an API design is only for developers to figure out. That isn’t true. Product managers, business stakeholders, and external developers should all be involved as well.
Organisations that view APIs as strategic and transformative to the business will take 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.
2. Offer a preview release for feedback
Once your team has implemented some or all of endpoints that are part of the release, the next step is to offer a preview release to your 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 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.
3. Identify any breaking changes
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.
A new API version can have a negative impact 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.
Review your APIs to determine who, if anyone, may be impacted by your API changes. The sooner you catch breaking changes, the sooner they can be resolved in some way. If the API endpoint has been used for some time, you may need to consider rolling out new API operations to offer the changed functionality rather than modifying existing ones and introducing a breaking change.
4. Perform a thorough security review
Time constraints cause us to take shortcuts and make assumptions. 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.
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 organisation. Don’t assume your API was designed to be used outside of the original use case – most never are.
I have found that organisations 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. Organisations 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.
5. Update API documentation, examples, and getting started guides
When releasing a new revision of your API, make sure your documentation remains clear and relevant. Poor documentation (or none at all) can lead to confusion by developers that will be integrating your API.
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 is isn’t trying to solve.
Additionally, add or update your code examples. Ensure your getting started guides are up-to-date and still relevant. At a minimum, your documentation should demonstrate how to accomplish simple tasks based on your API capabilities. Keith Casey wrote a great post on The Three Styles of API Documentation if you are still working on your approach to documentation.
6. Write a changelog
New releases should include a published changelog – a quick reference for what has been added or enhanced. 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.
Be sure not to expose implementation details, such as internal services or database schema changes. 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.
7. Identify API management layer configuration updates
API gateways and API management layers provide a bridge between your code and your API consumers. While your configuration may proxy all authorised calls to your backend API, some endpoints may require additional security or fine-grained access control. Be sure to update your API management layer (APIM) with any new URLs and associated security rules and rate limits.
When possible, I encourage organisations to automate this process as part of your CI/CD automation. This 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.
8. 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 (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, frustration, and reduce customer churn.
9. Update all API test automation scripts
Releasing an API without tests is very risky. 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. This is the minimum level of testing required before releasing an API.
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. Consider adding acceptance testing to your test strategy, or expand your acceptance tests to include any additions or changes in the new release. In my opinion, acceptance testing is the most valuable testing approach for an API. It looks for both implementation correctness and that it supports intended usage.
10. Write an announcement
Draft an announcement about the new release. Include the changelog, mentioned earlier, along with other important details about the release. Announcements often generate interest, excitement, and the understanding that your API is under active improvement rather than becoming stagnant.
Finally, remember that internal APIs need a release checklist as well. Just because the target developers are nearby, properly verifying and communicating your releases help to keep your audience updated.
