Versioning

String Theory uses a (surprisingly) unique approach to versioning. This article describes how it works, and why we chose it.

Endpoint based versioning

Instead of versioning the entire API, String Theory versions each endpoint individually . This means that it is extremely common that you’ll be consuming endpoints with different versions when using String Theory.

For example, at the time of writing the following endpoints were the recommended latest versions:

• /v2/deposit/cancel
• /v3/holds/release
• /v1/owner/balances

Since all endpoints are compatible with each other , you can use /v2/deposit/cancel and /v3/holds/release and /v1/owner/balances in the same implementation without worrying about compatibility issues.

This also means that the overall String Theory API is not versioned. There is no String Theory 1.0 or 2.0, instead you consume the version of the endpoints that meet your needs.

Why version endpoints individually?

We believe endpoint specific versioning makes it significantly easier for our consumers to incrementally upgrade their implementations.

Let’s go through an example:

1. The String Theory team finds a significant flaw in the /v1/exchange endpoint, and needs to fix it with a breaking change.
2. As a result they create /v2/exchange with the breaking change and move /v1/exchange to deprecated.
3. The consumer using /v1/exchange is notified that the endpoint has been deprecated and they need to move to /v2/exchange
4. The consumer can upgrade just their usage of /v1/exchange without getting any incidental changes to the rest of their implementation.

We believe that a lot of dependency fatigue (and corresponding lack of updating) is caused by having to upgrade to all new versions of an API all at once. It’s common to upgrade to a new version of an API (or dependency) for a small change, only to find out that several other parts of your implementation are now incompatible. This routinely turns what should be minor work tickets into projects that suck up significant time and resources.

The endpoint specific versioning strategy is designed to help make it so that when you need to upgrade to a new version of an endpoint, you can focus on just that endpoint and not worry about the rest of your implementation.

Versioning rules

These rules do not apply to beta endpoints.

• String Theory never makes breaking changes to an endpoint version
  • Example: Fields are never renamed without a version change
  • Example: The type of a field is never changed without a version change
  • Example: Required fields are never added without a version change
  • Example: Fields are never removed without a version change
• String Theory may make non-destructive changes to an endpoint without changing the version
  • Example: Adding an optional field to a request body
  • Example: Adding an additional field to a response body
  • Example: Adding an allowed value to an enum
• String Theory does not remove versions unless they were first deprecated

Choosing a version

The API Reference has a current section that is kept up-to-date with the latest version of each endpoint. This is the version you should be using for all new implementations. Supported endpoints are also available for use, though not recommended. Finally, deprecated endpoints are at end of life and will be removed. It is strongly recommended that you not use deprecated endpoints in new work and migrate existing usage to a newer version to avoid disruption.

Endpoint Lifecycle

String Theory endpoints have a lifecycle that they move through starting with beta, and ending in removal from the API. Here is a list, which we’ll cover in more detail below:

• beta
• current
• supported
• deprecated
• removed

Beta

These are new “bleeding edge” endpoints that are still in development. They are not recommended for production use as the interfaces are not stable and may change without a corresponding version change. If you find yourself in need of a beta endpoint, please reach out to us to discuss your use case and timeline for a stable release (if any is planned).

Most beta endpoints will eventually become current, but due to their experimental nature, some might be removed instead if they turn out not to be viable.

Current

These are the latest stable version of an endpoint. They are recommended for production use as the interfaces are stable and will not have breaking changes without a corresponding version change.

When a newer version of a current endpoint is released, the older version is moved to either supported or deprecated depending on whether or not the old version will have long term support. No current endpoints are ever removed without first moving to deprecated.

Supported

These are endpoints that have a newer version in the current section, but still have long term support. It is not recommended to use these endpoints for new development, but if your implementation already relies on them there is no pressing need to upgrade.

String Theory chooses what moves to supported instead of deprecated based on several factors, but the biggest ones are:

• Usage of the endpoint
• How long the endpoint has been in current
• If the endpoint is being replaced due to recently discovered bugs or other issues

Deprecated

These are endpoints that String Theory is actively working on removing from the API. These are removed at String Theory’s discretion, generally once we’ve worked with consumers to give them notice and time to migrate off of them. However, we only consult with consumers that were using the endpoint version when it became deprecated so any new users will not be notified and we may remove the endpoint without warning.

Removed

This isn’t an official state, but means we’ve permanently remove an endpoint from the API. This will only happen to deprecated endpoints and beta endpoints that never made it to current.