API Versioning and Deprecation on the SAP Ariba Developer Portal

When a new version of an API is released, the previous version is deprecated; a single SAP Ariba Developer Portal discovery page hosts both versions.

This topic describes the the policies and best practices that apply when a new version on an API is published on the SAP Ariba Developer Portal, triggering the deprecation and eventual decommissioning of the previous version.

You can view a list of deprecated and decommissioned APIs by choosing Deprecated & Decommissioned APIs from the gear-shaped settings menu near the top of the SAP Ariba Developer Portal. This list displays each API that has one or more versions in the deprecated or decommissioned states. Users can drill down within a listed API to see the deprecated and decommissioned versions. Clicking View active version opens the discovery page for the active version of the selected API.

Versioning

A version indicator located directly below the API name identifies which version of the API is currently displayed on the discovery page for an API. When only one version is available, this version indicator is a simple label. When multiple versions are available, it is a dropdown labeled Version X where X is the displayed version number. Users can opt to switch to a different version by choosing from this dropdown. The most recent version is displayed by default.

Information such as runtime URLs, endpoints, and models presented on the discovery page relate to the displayed version.

To write an application using a particular version of an API, use the runtime URLs specific to that version. Different versions distinguish their runtime URLs by modifying the version number. For example:

Version 1

https://openapi.ariba.com/api/hypothetical_api/v1/prod

Version 2

https://openapi.ariba.com/api/hypothetical_api/v2/prod

Version 3

https://openapi.ariba.com/api/hypothetical_api/v3/prod

Deprecation

When a new version of an API is published on the SAP Ariba Developer Portal, the old version is deprecated, with the following effects:

  • The deprecated version is marked Deprecated in the version control dropdown on its SAP Ariba Developer Portal discovery page.

  • If you navigate to the discovery page for the deprecated API by choosing the deprecated version from the version control dropdown, a message indicating the date of deprecation appears at the top of the page.

  • Existing client applications that call the deprecated API will be supported for 12 months and will work until the API is decommissioned. If you call a deprecated API, the response includes an X-API-Warn header indicating that the version is deprecated and identifying the active version.

  • However, no new client applications can request access to the deprecated version of the API; all new client applications must request the new version.

Decommissioning

At the discretion of SAP Ariba, the API version is eligible to be decommissioned after being in deprecated or active state for a minimum period of 24 months which must include at least 12 months in a deprecated state.  Decommissioning an API version has the following effects:
  • The decommissioned version is marked Decommissioned in the version control dropdown on its SAP Ariba Developer Portal discovery page.

  • The decommissioned API should not be called at all, and if called might not provide expected responses. Existing client applications that use the decommissioned API may no longer function. If you call a decomissioned API, the response includes an X-API-Warn header indicating that the version is decommissioned and identifying the active version.

  • No new client applications can request access to the decommissioned version of the API; all new client applications must request the new version.