API Stability: To change or not to change?

APIs are the glue that connects different parts of your application together and, whether internal or public, they dictate how components talk to each other. So, should you aim to keep them stable throughout your project’s lifecycle? The surprising answer is, not always.

Internal APIs: Flexible yet clean

For most internal APIs, flexibility, not stability, is key. The reality is, we rarely get everything right on the first try. Often, it’s only after using an API in real-world scenarios that you find opportunities to make it more intuitive, efficient, or reliable. Embracing changes and refactoring your internal APIs is part of keeping your codebase in good shape.

For example, let’s say you create an API for handling customer data. Initially, it works well. But as the application grows, you realize it could be more streamlined, or it’s missing certain flexibility for new use cases. By periodically revisiting your internal APIs, you can refine them to avoid long-term technical debt.

Why do clean APIs matter? Keeping internal interfaces clean, easy-to-use, and adaptable minimizes "cruft" – unnecessary complexity and outdated code that can slow down your team over time. When an API feels either awkward or over-engineered, it’s a sign you might need to refactor it.

External APIs: Insulated and frozen

When your API is public facing, however, stability becomes crucial. Any changes can ripple through to clients, causing breaks or requiring adjustments for external users. This is why public APIs need a different approach.

• Consider an external API stability strategy. Try to "freeze" your external APIs as much as possible. If you must make changes, do so cautiously, and consider adding versioning to allow clients time to transition without breaking their existing implementations.
• Consider creating a buffer layer. A practical solution for updating a public-facing API is to create a buffer layer between your internal code and the external API. This layer allows you to refactor and improve the internal API without impacting the clients who are relying on your external interface. Keep this layer minimal and avoid "leaking" internal details that might limit your flexibility to change it in the future.

Source stability guarantees

API source stability guarantees assert that future changes to the API will not break source code written against it. Consequently, developers can rely on the API to remain consistent, avoiding the need for constant rewrites or adjustments as the API evolves. These guarantees are commitments offered by the code or library author, and cover a range of options such as strict source code compatibility (all existing code will run without modification on all future versions of the API), backward compatibility, deprecation and/or sunset periods, version-limited stability, to no guarantee at all (code is in prototype and/or early development).

Whether to provide a source stability guarantee depends on the use case, audience, and lifecycle of the API. If your API is public or widely adopted, if it’s used for a long-term project, or it’s part of a high-level library or framework, then you probably want to consider some form of source stability guarantee so that users of your API know what to expect.

SemVer

One common example of a source stability guarantee is version-limited stability, conveyed when an API uses Semantic Versioning (SemVer). SemVer provides a formal structure for version numbers and outlines the conditions that allows them to be modified. Below is a short summary; for the full set of rules governing visit semver.org.

• Version numbers follow the format MAJOR.MINOR.PATCH.
• The MAJOR number changes when there are breaking API changes, the MINOR number changes for backward-compatible additions or deprecations, and the PATCH number changes for completely backward-compatible updates.
• Version 0.x.y represents initial development, where anything can change at any time, and the public API is not fixed.
• Version 1.0.0 marks the first release with a stable, public API.
• Versions can also include extensions such as pre-release identifiers or metadata labels.

While using SemVer within an internal development team might seem like overkill, it helps avoid unexpectedly broken APIs. By building trust and facilitating clear communication about changes, it enhances collaboration both within the team and with any external stakeholders.

SemVer benefits

One of the biggest benefits of SemVer is that, since any breaking change requires a major version bump, it encourages careful design. Changes must be deliberate to avoid unnecessarily disrupting users. No engineer wants the major version of their component to be in the double-digits, which incentivizes API designers to consider long-term stability and extensibility.

SemVer emphasizes maintaining backward compatibility within the same major version. This principle encourages thoughtful API design practices, such as deprecating features gracefully rather than abruptly removing them and avoiding unnecessary breaking changes that could alienate users or slow adoption.

What about the ABI?

Application binary interface (ABI) stability ensures that compiled programs can work with updated versions of a library without requiring recompilation. A strategy for maintaining shared libraries, ABI stability makes it easier to roll out bug fixes, security patches, and performance improvements. Maintaining a consistent ABI minimizes disruptions in complex systems without requiring source recompilation, and so helps create long-term system stability.

However, making software ABIs static also imposes constraints on development since it limits changes to function signatures and data structures to avoid breaking compatibility, which leads to accumulating technical debt. This inflexibility means you should offer ABI stability guarantees only when absolutely necessary, not by default. In fact, for internal libraries you may not need public APIs at all, freeing you from carrying the burden of SemVer versioning and a fixed API/ABI, allowing you to make changes at will.

Balancing flexibility and stability

Ultimately, managing API stability is about balancing flexibility and stability. For internal APIs, don’t be afraid to change them as you learn – refactoring helps keep your codebase fresh and maintainable. For external APIs, prioritize consistency to avoid disrupting end users. This dual approach helps you maintain clean, adaptable code internally while delivering reliable, stable interfaces to external clients. For more on this and other software development topics, see our best practice whitepapers.