Skip to main content

GraphQL API policy

This section describes the AppDirect GraphQL API lifecycle, the backwards compatibility policy, and contains the API changelog. This policy is based on AppDirect's product lifecycle phases, but is focused on APIs specifically.

API lifecycle​

| API status | Duration | API updates | SLA | API support | API docs | |------------------------|------------------ ------|------------------------------------------------------------|-------|--------------------|----------------------------------| | Preview | 3-6 months | Yes ("breaking changes" possible) | No | Limited | Partial | | Early Availability | 3-6 months | Backward compatible only (no "breaking changes" allowed) | Yes | Full | Complete for target use cases | | General Availability | -- | Backward compatible only (no "breaking changes" allowed) | Yes | Full | Complete | | Deprecated | 6 months1 | Backward compatible only (no "breaking changes" allowed) | Yes | Full | Complete | | Retired | 6 months1 | None | No | None | Available (no further updates) | | Decommissioned | N/A | None | N/A | N/A | None |

Preview​

New features of the AppDirect GraphQL API might be made available as preview product offerings. Preview APIs are available to AppDirect partners who are interested in testing and providing feedback on upcoming functionality.

note

AppDirect does not guarantee that preview functionality will be promoted to the official AppDirect API.

Breaking changes to preview APIs can be introduced throughout the preview program so it is strongly recommended that these APIs not be used in production deployments. Technical support and service-level agreements do not apply to preview APIs.

All preview schemas are accessible through the following endpoint:

https://<marketplaceHost>/api/graphql/preview

See Preview schemas for more information on how to access and use the AppDirect Preview GraphQL API.

Early Availability​

APIs in Early Availability (EA) 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.

Enhancements and bug fixes will be available through the schema on the production endpoint, the same endpoint that will be used when the API is in General Availability. All changes will be fully backwards compatible. See Backwards compatible changes for examples of possible backwards-compatible changes to the GA AppDirect GraphQL API.

The official GA GraphQL schema is accessible through the following endpoint:

https://<marketplaceHost>/api/graphql

General Availability​

When new API functionality becomes available through the official GraphQL schema, it is considered generally available (GA). Generally available API functionality is covered under all technical support and service-level agreements for a minimum of two years.

While GraphQL API functionality is GA, enhancements and bug fixes will be available through the GA schema on the production endpoint. All changes will be fully backwards compatible. See Backwards compatible changes for examples of possible backwards-compatible changes to the GA AppDirect GraphQL API.

The official GA GraphQL schema is accessible through the following endpoint:

https://<marketplaceHost>/api/graphql
note

The AppDirect GraphQL API is not yet GA, and the production endpoint is not accessible.

Deprecation and Retirement​

As the GA GraphQL schema is enhanced and new functionality is released, AppDirect might deprecate and subsequently retire obsolete or outmoded functionality. When this occurs, the associated fields and operations in the GA GraphQL schema are marked as deprecated and include a retirement date that defines when technical support and service-level agreements no longer apply. Retirement dates correspond to the first production release of each quarter (January, April, July, October) and are set at least two years after the deprecated field was originally introduced.

Users of the GraphQL API will be notified at least six months before schema fields and operations are retired. Deprecated and retired functionality will also be recorded in the Changelog.

note

GraphQL schema fields and operations that are marked as deprecated but have not yet reached their retirement date will continue to be covered under all technical support and service level agreements until the retirement date is reached.

AppDirect strongly encourages developers to migrate to the latest GA functionality before retirement.

Decommission​

After API functionality is retired, AppDirect reserves the right to decommission it. When API functionality is decommissioned, the associated schema fields and operations are removed and no longer continue to operate.

Users of the GraphQL API will be notified at least six months before an API decommission goes into effect. Decommissioned functionality is also recorded in the GraphQL API Changelog.

Breaking changes associated with decommissioned functionality are introduced with the first production release of each quarter (January, April, July, October).

Backwards compatibility​

Both the Preview and EA/GA versions of the AppDirect GraphQL API will be enhanced over their lifecycle. Some changes will be backwards compatible (non-breaking) and some might not be backwards compatible (breaking). The following section illustrates the differences.

note

See Changelog for a full list of upcoming and past breaking changes for the GA GraphQL schema.

Backwards compatible changes​

The following is a list of possible changes that could be made to a GA API that are considered backwards compatible:

  • Adding a new query, mutation, or type

  • Adding a new field

  • Adding a new value to an enum, which is used as an input argument (for example, a new orderBy clause)

Non-backwards compatible changes​

The following is a list of possible changes that could be made to an API that are considered not to be backwards compatible:

  • Removing or renaming an existing field, enum or enum value

  • Removing an existing query or mutation

  • Removing an existing type

  • Changing a "non-null" field to "null"

  • Removing a schema directive

  • Adding a mandatory argument to a field

  • Changing the type of a field (for example, changing a String to an Int)

Preview schemas​

Preview schemas allow AppDirect partners to test and provide feedback on upcoming functionality. All preview schemas are accessible through the following endpoint:

https://<marketplaceHost>/api/graphql/preview

Because the preview endpoint might host multiple preview schemas at any given time, you might be required to provide a custom media type in the Accept header for your requests. The value sent in this header determines which preview schema is used to fulfill your request.

Was this page helpful?

Tell us more…

Help us improve our content. Responses are anonymous.

Thanks

We appreciate your feedback!