If your team is developing or updating an API as part of your software project, you need to be careful about making changes to that API. Those changes could cause unexpected bugs or failures and leave an unpleasant surprise for team members unaware of the changes. A lack of communication or coordination can turn even small issues into bigger ones for your organization.

It’s important to document and share API changes with your team as well as other stakeholders. In this article, you’ll learn some best practices you can use to share API changes and avoid bugs due to API updates. You’ll also learn about tools like Optic that you can use to track and share API changes.

What API Changes Cause Problems?

The following are some examples of API changes that could cause bugs in your software.

Changing the Response Object of an Endpoint

Assume you have a simple Flask API. On the left is your original API with a single endpoint, which returns information like ID, first name, last name, and full name. You decide that first name and last name are redundant since they can be derived from the full name using a simple split operation; on the right is the same endpoint with the updated response object.

If one of your team members consumes your API as shown in the code snippet below, the change to your API would break their code:

import requests

responseObject = requests.get(apiUrl).json()

print(f"Your id is {responseObject['id']}")

print(f"Your name is {responseObject['fname']} {responseObject['lname']}")

This sort of bug could also occur if you update the names or data types of some of the fields in your response object.

Changing the Name or Structure of an Endpoint

The two code snippets above differ by only a single letter. On the left, the endpoint uses user, while on the right it uses users.

If a team member consumes the API as shown below, the update would break their code, because the request would be made to a nonexistent URL:

import requests

responseObject = requests.get('www.api.com/user/1').json()

print(f"Your id is {responseObject['id']}")

print(f"Your name is {responseObject['name']}")

Updating the Response Code of an Endpoint

If you update the error response code for one of your API endpoints from 500 to 404, it could cause a bug. Consider the code snippet below:

import requests

responseObject = requests.get(apiUrl)

if responseObject.status_code == 500:
    # Handle Error
    pass
else:
    # Use data from API
    pass

If someone implements error handling but checks for a status code of 500, the new response code of 404 would not be handled. As a result, the code in the else block would be executed and lead to an error.

Making Optional Parameters Required

If you make optional parameters required, you could potentially run into another issue. Assume you have an endpoint that returns books from a book database. The endpoint accepts an optional parameter for the number of books to be returned, set to ten by default. If you later decide to make the number of books a required parameter, anybody who had previously used your endpoint without passing the optional parameter would face errors.

The above are just some of the possible problematic changes. Even updating things such as authentication or rate-limiting values can cause bugs in your team members’ code.

Why Share API Changes with Your Team?

In addition to the possibility of breaking changes, the following are other reasons to share changes with your team:

• Team members could provide valuable feedback that might otherwise get lost. It's important to consider the potential implications of any API change before taking action, and having your team on board will help ensure that you're making the right choice.
• They need to prepare for API changes. This might include testing the changes or making sure that their code is compatible with the new API. They need to be able to account for the changes in their code; otherwise, they could be caught off guard by unexpected issues or errors, which could damage relationships between team members.
• Not only could changes break your API, but they could cause damage to other applications that use the API. If your team didn’t know about the changes, they wouldn’t be prepared to handle the consequences.

How Should You Share API Changes?

There are multiple ways that you can keep your team informed of changes. Here are some options.

Code Reviews

You can set up a code review system to ensure any updates to your API are reviewed by your team members before they’re finalized. This gives your team a chance to identify issues and suggest enhancements.

Tools like Optic allow you to review these types of changes. Below is a sample API changelog generated by Optic:

Optic also offers a GitBot that can add API changelogs to every pull request you make:

Communication Channels

One way to make sure that your team is aware of any API changes is to use a separate channel for sharing these changes—for instance, a Slack channel or an email list. This will ensure that everyone knows what to expect. Below are a few tips to manage such a channel:

• Make it a read-only channel to avoid any discussions. Your team should be able to check notifications without having to scroll through other messages.
• Ensure that potential breaking changes are clearly noted. You could add [IMPORTANT] at the beginning of your message or add a red background.
• Communicate about such changes well in advance. This will give your team time to prepare for them.

API Documentation Updates

When it comes to API changes, having comprehensive and up-to-date documentation is essential. This will help ensure that everyone on your team understands the changes and knows how to implement them.

The documentation can either be updated manually or through automated services such as Swagger or Postman. Optic, for instance, analyzes requests, responses, and traffic to your API to more accurately document it and present changes. Read more about how Optic handles API changes in documentation.

API Contract Testing

If you are updating your API based on user feedback, you can work with your team or stakeholders to build an API contract describing how your API should function. You can use JSON schemas to document your API’s endpoint response codes and set up the contract. The contract must be accepted by all parties. Then, any changes made to the API must pass the contract test before being approved. Contract testing can be automated and incorporated into your CI/CD pipeline. Contract testing tools include Pact and Spring Cloud Contract.

Documentation-Driven Development

This is similar to test-driven development, but instead of writing tests first, you will write the documentation before developing your API. This means any changes made to your API will have to be documented first. You can follow OpenAPI standards to write the documentation, or use a service like Optic to compile the documentation instead of doing it manually.

Versioned APIs

Using versioned APIs allows team members and end users to continue working with an older version of your API while they update their code to work with the newer version. This significantly reduces the impact of any breaking API changes. But it comes at a cost, since you might still have to provide support for older versions. You will also need to maintain additional documentation to ensure users can still use older versions.

Ensure your API is backward compatible; if a user is able to use a previous version of your API, they should either be able to use future versions of your API without any changes or still be able to use the previous version. This can be done by providing support for both versions of the API and adding a deprecation warning to the old API to let the user know they will have to migrate soon.

You could also define your API URLs so that the version number is included. For example:

www.myapi.com/v1/getBooks

This would ensure that any updates or new releases of your API don’t break your team member’s or end user’s code if they use the previous version.

Conclusion

Even small changes to your API’s response object or URL can have a big impact on other team members or stakeholders. It’s important to keep your team informed. Having a good workflow to share API changes, document them, and test them will prevent errors or other problems down the line.

One way to improve your API development workflow is to use Optic to automate testing, documentation, and transparency of changes. The tool tracks and reviews API changes by generating a changelog, then uses requests, responses, and traffic to your API to generate documentation.

Want to know more? Optic is an open source project, so you can join the community working hard to make writing documentation easy