API Deprecation

API Deprecation

An API-first approach ensures that your developer teams can add, test, and deliver changes faster than traditional tightly coupled platforms. In legacy platforms, services were not designed to function independently, requiring significantly more workarounds and testing to make all parts work together.

Commerce APIs give you the control to design and launch differentiated customer journeys across browsing, checkout, and post-purchase engagement.

In today’s fast-paced commerce and technical landscape the only constant is change. Software needs to adapt and evolve to keep up with the changing set of demands. One option a company may choose is deprecating and disabling APIs as they release updated versions. This constant deprecation creates undue burden on API consumers as the constant release cycle incurs costs, frustrations, and unnecessary maintenance.

A comparison snapshot:

In our decades of business, we have seen other companies deprecate APIs for a wide range of reasons, each having massive impacts on end-users.

Why deprecate an API?

• It no longer supports use cases.
• It is insecure.
• It has too many bugs.

Why disable an API?

• It no longer serves a business objective.
• Investment in a different product variant.
• It cannot be supported from a cost perspective.

If the API is meticulously designed and maintained, most of these reasons never apply. The one exception is APIs that no longer support the intended use case. A recent example is PayPal’s changing their checkout options making the old APIs irrelevant.

Ideally deprecation will not disrupt business as usual for users given there is a timely update or alternative in place. It’s recommended to communicate early with an explicit timeframe, release schedule, and a support plan.

In our case, there were no customers leveraging the API before the end-of-support was officially announced. This was possible by following a set of best practices.

Deleting an API carries far more risk since there is no update. It is vital companies are fully aware of the impact prior to disablement.

Best practices to consider when deprecating an API:

• Using an API management tool allows for quick access to users and will make communication easier prior to deprecation.
• Provide an appropriate sunset period; rule of thumb is 3-8 months depending on the service offering.
• Effective versioning gives developers enough time for the necessary work to support the new API.
• When versioning is done right, the updated API is built and released prior to deprecating the previous version. Communicate through a developer portal and the API documentation.
• Honor all SLAs prior to deprecation.
• Have a migration plan in place to preserve user relationships and reputation.

An essential final step is to set up usage monitoring prior to the removal date. This way you can alert any users still using the old API. Overcommunication is better than surprised and frustrated users.

The Potential of Higher Cost in Deprecation

Even with all of the best practices in place, a common disadvantage of API deprecation is technical debt. You will find with many of our competitors who in some cases deprecate every quarter, there is significant development time that translates into cost. You may end up paying on a maintenance contract to move from one API to the next.

A Better Way Forward: The Versionless API

Elastic Path Commerce Cloud has adopted a new approach, versionless APIs. By defining a future-proof API contract, we can continue to optimize performance, roll out code patches, and update dependencies without the need for customers to modify their integrations. This approach moves the complexity from the API end-users to the API engineering team ensuring our customers can stay focused on innovation, such as tapping into new channels or what is most important to their business going forward.

When compared to our competitors our customers see lower maintenance costs, tighter security through constant updates, and enjoy performance improvements immediately instead of after the next large IT project.

More and more companies are understanding the value of APIs as a product. No longer operating in silos, companies are beginning to adapt to the API-first economy of tomorrow by using both third party APIs and providing their own to other businesses.

A Closing Thought:

API deprecation is unavoidable, but when absolutely necessary we take all due care with clearly communicated timeframes (a 90-day minimum), and documentation. In those instances when we had to deprecate we have done so to avoid confusion to end users in the case of removing unused settings, and in the instance when a partner payment gateway provider initiated the process.