Versioning

APIs

When we introduce changes to our APIs, we follow best practices to have the least disruption on existing integrations. For example, for our APIs, we follow the API expand-contract pattern to add new elements without changing the version.

While we strive to reduce impact to existing integrations, we sometimes have to introduce changes that are not compatible with existing API versions. Doing so enables us to keep our APIs consistent and to improve the quality and developer experience.

When we introduce a breaking or incompatible change, we release a new API version to accommodate the change. And we update the Picsart API version when making breaking changes. We number the versions in order.

Checking the API version

Each API has a different version. When making direct calls from your server you can see the API version in the URLs that you use to reach the Picsart platform.

Each API URL contains a version suffix starting (note: there are exceptions, see below) with either "v" or "V" character followed by a whole number to indicate the API version. We increment the number for every version, but we may skip numbers when needed.

Here are some examples of different API versions:

api.picsart.io/1.0/        // version 1
video-api.picsart.io/v1/   // version 1
video-api.picsart.io/v2/   // version 2

The current version of the Programmable Image API is version 1.

Older versions of the API will keep working like before even when we bring out new versions. We won't automatically change your API version, so your integrations will stay working until you're ready to switch.

📘

See our release notes

Whenever we make changes to our API or developer tools, we update our release notes. They give you lots of details about what's changed and how to update.

To check if you're using the latest API version, refer to the release notes.

Breaking changes

A breaking change is a change that might make you need to change your code to keep things working. They're sometimes called changes that don't go backward.

Some examples of breaking changes:

• Removing or renaming a parameter or field in the request ❌
• Adding a required field to a request body ❌
• Changing a field from optional to required in a request body ❌
• Adding a required header to a request ❌
• Removing or renaming an endpoint or operation ❌
• Changing how an endpoint works ❌
• Adding validation for a field ❌
• Changing error handling ❌
• Removing a field from a response body ❌
• Changing a field from required to optional in a response body ❌
• Removing a header from a response ❌
• Changing the HTTP status code of a response ❌
• Changing error codes for an existing error ❌
• Renaming a field in a request or response ❌
• Changing the type of a field in a request or response ❌
• Changing the behavior in a way that requires API consumers to change their integration for it to work properly.
  For example, if an API was ignoring some errors and now starts returning a validation error, the change is a breaking change. ❌

We don't automatically change your API version. You can opt in to new versions of the API in the dashboard when you're ready.

Non-breaking changes

We may make non-breaking, small changes to the API. These are changes that won't mess up things you're already doing, so you can use them whenever you want. They're sometimes called backwards compatible changes.

Some examples of non-breaking changes:

• Adding new endpoints or operations ✅
• Adding new optional fields to responses ✅
• Adding new optional request parameters or body ✅
• Changing a field from required to optional in a request parameters or body ✅
• Adding an optional header to a request ✅
• Changing field ordering in responses ✅
• Changing a field from optional to required in a response body ✅
• Adding a header to a response ✅
• Changing the case of a header name ✅
• Changing the value of a header ✅
• Changing the text of an error message in a response ✅
• Add a new HTTP status code for the response ✅
• Deprecating a request or response field (for documentation) ✅

We'll update our developer changelog with information about non-breaking changes.

New API version without changes

In some cases, we may introduce a new API version without visible changes to API consumers. We do so to improve stability and consistency of our APIs, or to implement some groundwork for bigger changes in the future.

For the same reason, we sometimes skip numbers in a versioning of specific APIs.

Upgrading to a new API version

In general, we recommend upgrading to new API versions whenever possible. Keeping your integration up-to-date is crucial so you can take advantage of recent developments and improvements in our platform. However, if you decide stay in your current version, you can continue to do so. We maintain older versions of our APIs that you can continue to use until you are ready to upgrade.

To prepare for an API upgrade, refer to the release notes to find out about changes.

Deprecation

Right now, we're not stopping older versions of our API. But if we ever plan to do that, we'll tell you about it well before it happens, in plenty of time.