Versioning

All StackPath API request paths begin with a service name and a version number. The version number denotes the call's stability and backwards compatibility.

Version Anatomy

Version numbers begin with the letter "v" and include at least a major version number and an optional stability level. For instance:

Stability

API calls have either "alpha", "beta", or "stable" stability levels. A call is considered stable if it doesn't state alpha or beta level stability in the version number.

Alpha

Alpha version API calls are a great way to explore StackPath's most cutting edge features, but they may be limited to a specific set of users and should be considered unstable. They may have bugs or unknown side effects, and their inputs and outputs may change before they're promoted to a beta or stable state. We highly recommend caution when using alpha API calls. Please employ them on non-production Stacks or in an environment that's backed up and easy to restore.

Please contact your account manager if you spot an alpha API call that you'd like to try out but receive a 403 Forbidden response. We may be able to enable the call for your account or Stack.

Beta

Beta version calls also expose pre-release functionality, but they're available to every StackPath user, and their inputs and outputs should not change before they're promoted to the stable tier. As with alpha calls, please take caution as these are also considered unstable and may have bugs or side effects.

📘

Please reach out to our support team if you spot issues in alpha or beta functionality.

Stable

Stable calls have passed through an alpha and beta period as well as internal testing by StackPath and are safe to use for all StackPath users. Please use stable calls for all of your infrastructure automation. Changes to these calls preserve backwards compatibility until a new major version number of the call is released.

Version Numbers

All versions include a number that denotes a semantic versioning major version. All changes to calls with this number are ensured to be backwards-compatible. If StackPath needs to change an API call in a way that requires users change their API clients or call handling then they increment this version number by one. This typically happens when there are major changes to a call's input or output structure.

If a new version of an API call is released then the call's previous version may remain the same or become deprecated for eventual removal from the StackPath platform. StackPath will communicate with their users accordingly if that happens to ensure a smooth transition to the new call version.

📘

The StackPath API's versioning scheme is inspired by Google Cloud's versioning and stability guidelines. If you're familiar with Google's versions then you should also feel comfortable with StackPath's API versions.