Skip to main content

REST API versioning policy

API organization

AppDirect REST APIs are organized around core services that are each versioned independently and represent a base set of capabilities of the AppDirect platform. The version number of an API is referenced in the URL path for that API. The separate concerns are versioned individually. The version status is indicated in the reference documentation and will be communicated as described in this document.

The following is a list of current AppDirect APIs:

APIDescriptionBase path
Marketplace APIList products, editions, bundles, and more for a storefront experience./api/marketplace/v1
Subscription Management and Billing APIView and update purchases, subscriptions, invoices, payments, and other billing data./api/billing/v1
Account APIManage companies, users, groups, authentication and other identity data./api/account/v1
/api/account/v2
Reports APIList and download reports generated in the platform./api/reporting/v1
/api/reporting/v2
Channel Administration APIConfigure and view exchange rates, discounts, webhooks, notifications and other core parts of the platform./api/channel/v1
Customer NotificationsManage email and SMS templates./api/notification/v1
Leads APIManage leads./api/prm/v1
/api/lead/v2
Payment Methods APIManage payment methods./api/appMarket/v2
Assisted Sales APIManage opportunities./api/assistedSales/v1
Reseller APIPerform reseller operations./api/appReseller/v1
/api/reseller/v1
Product Integration APISubscription sync and metered usage APIs./api/integration/v1
/api/sync/v1

Versioning policy

This section describes the stages that different versions of AppDirect APIs pass through over the course of their lifecycles. AppDirect will communicate status changes beforehand, as indicated in the following table, and the API reference documentation will indicate any API that has a status other than General Availability (GA).

Summary

API statusDurationAPI endpoint availabilityAPI updatesSLAAPI supportAPI docs
Preview3-6 monthsPublicYes ("breaking changes" possible)NoLimitedPartial
Early Availability3-6 monthsPublicBackward compatible only (no "breaking changes" allowed)LimitedFullComplete for target use cases
General Availability2+ yearsPublicBackward compatible only (no "breaking changes" allowed)YesFullComplete
Deprecated6 months1PublicBackward compatible only (no "breaking changes" allowed)YesFullComplete
Retired6 months1Public (no enhancements)NoneNoNoneAvailable (no further updates)
DecommissionedN/AUnavailableNoneN/AN/ANone

Preview

AppDirect APIs might be made available as a preview offering to selected customers. Preview APIs are available to AppDirect partners who are interested in testing and providing feedback on upcoming functionality.

AppDirect does not guarantee that Preview APIs will be promoted to General Availability as defined below. Breaking changes to beta APIs can be introduced throughout the beta program so it is recommended that beta APIs not be used in production deployments. Support and service-level agreements (SLAs) do not apply to beta APIs.

Early Availability

APIs in Early Availability are available in production to a limited number of customers based on fit with one or more specific use cases. SLAs do apply and support is available for participating customers. APIs should perform well for the selected customers and at limited transactional volume for the targeted use cases. AppDirect informs participants of known issues and limitations.

General Availability

APIs in General Availability are fully supported and apply to all existing service-level agreements. While an API is generally available, additional functionality, data, and bug fixes are made available through the API. All changes are fully backwards compatible. See Backwards Compatible Changes below for a summary of backwards compatible changes that might be made to GA APIs.

All GA versions of an AppDirect API will be supported for a minimum of two years.

Deprecation

When a new version of an API is released, AppDirect will deprecate any previous versions of that API that are two or more years old. API users will be notified at least six months before the API deprecation goes into effect. Deprecated APIs continue to operate after the deprecation date but are no longer supported and SLAs no longer apply.

AppDirect strongly encourages developers to migrate to the latest API version prior to deprecation.

Decommission

After an API is deprecated, AppDirect reserves the right to decommission the API. When an API is decommissioned, its endpoints will no longer be publicly available. API users will be notified at least six months before an API is decommissioned.

Backwards compatibility

All Beta and GA versions of AppDirect APIs will be enhanced over their lifecycles. Some changes will be backwards compatible (non-breaking) and some might not be backwards compatible (breaking). This section describes the differences.

Backwards compatible changes

The following is an exemplary list of changes that might be made to a GA API that are considered to be backwards compatible:

  • Adding a new optional data field to an existing request message
  • Adding a new field to an existing response message
  • Adding a new method to an existing API resource
  • Adding a new API resource

Non-backwards compatible changes

The following is an exemplary list of changes that might be made to a Beta API that are considered to be non-backwards compatible:

  • Adding a new required data field to an existing request message
  • Removing an existing method for an API resource
  • Removing an existing API resource

Was this page helpful?