Stop Breaking Changes
An OpenAPI breaking change refers to a modification or update made to an API's contract (defined using the OpenAPI Specification) that introduces incompatibilities with existing client applications or consumers of the API. These changes can disrupt the functionality of client applications and potentially cause them to break or malfunction.
To avoid breaking changes, developers need to follow two basic rules:
However, in practice, these rules are very difficult to follow because of the complexity of OpenAPI.
There are many unexpected ways a developer could mistakenly break these rules.
Moreover, many development teams are generating OpenAPI specs from code, for example using FastAPI or oapi-codegen, which further contributes to the complexity.
Other examples of OpenAPI breaking changes:
Removing an API endpoint: If an existing endpoint is removed from the API, any client application relying on that endpoint will break when attempting to make requests to it.
Changing the data type or format of a response: If the structure or format of a response payload is modified, clients expecting the previous structure may encounter errors or fail to parse the response correctly.
Renaming or modifying existing request or response parameters: Altering the names, types, or locations of request or response parameters can cause issues for client applications that depend on the previous parameter configuration.
To prevent breaking changes in an OpenAPI-based API, consider the following practices:
Versioning: Use versioning to introduce breaking changes in a controlled manner. By assigning a version number to your API, you can maintain backward compatibility for existing clients while introducing changes in a new version. This allows clients to transition to the updated API at their own pace.
Documentation: Thoroughly document any changes made to the API contract. Clearly communicate modifications, including the affected endpoints, request/response changes, and any deprecations. Keep the API documentation up to date and accessible to developers to ensure they are aware of the changes and can adapt their applications accordingly.
Deprecation and Sunset Periods: If you plan to remove or modify existing API functionality, provide advance notice to the developers using your API. Consider implementing a deprecation period during which the deprecated endpoints or features remain available but are marked as such. This gives clients time to adjust their applications before the functionality is fully removed.
Semantic Versioning: Consider following semantic versioning principles when introducing changes to your API. Semantic versioning, such as using version numbers like MAJOR.MINOR.PATCH, helps convey the impact of changes. Breaking changes typically occur in major version updates, while minor and patch versions indicate backward-compatible changes or bug fixes.
API Testing and Monitoring: Implement comprehensive testing and monitoring strategies for your API. Automated testing can help catch issues and regressions early on, while monitoring usage patterns and error rates can identify potential issues caused by breaking changes in real-world scenarios.