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:

API	Description	Base path
Marketplace API	List products, editions, bundles, and more for a storefront experience.	/api/marketplace/v1
Subscription Management and Billing API	View and update purchases, subscriptions, invoices, payments, and other billing data.	/api/billing/v1
Account API	Manage companies, users, groups, authentication and other identity data.	/api/account/v1 /api/account/v2
Reports API	List and download reports generated in the platform.	/api/reporting/v1 /api/reporting/v2
Channel Administration API	Configure and view exchange rates, discounts, webhooks, notifications and other core parts of the platform.	/api/channel/v1
Customer Notifications	Manage email and SMS templates.	/api/notification/v1
Leads API	Manage leads.	/api/prm/v1 /api/lead/v2
Payment Methods API	Manage payment methods.	/api/appMarket/v2
Assisted Sales API	Manage opportunities.	/api/assistedSales/v1
Reseller API	Perform reseller operations.	/api/appReseller/v1 /api/reseller/v1
Product Integration API	Subscription 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 status	Duration	API endpoint availability	API updates	SLA	API support	API docs
Preview	3-6 months	Public	Yes ("breaking changes" possible)	No	Limited	Partial
Early Availability	3-6 months	Public	Backward compatible only (no "breaking changes" allowed)	Limited	Full	Complete for target use cases
General Availability	2+ years	Public	Backward compatible only (no "breaking changes" allowed)	Yes	Full	Complete
Deprecated	6 months1	Public	Backward compatible only (no "breaking changes" allowed)	Yes	Full	Complete
Retired	6 months1	Public (no enhancements)	None	No	None	Available (no further updates)
Decommissioned	N/A	Unavailable	None	N/A	N/A	None

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