API versioning

Prev Next

Overview

We keep improving our APIs. To do that without breaking the tools you’ve already built, we give our APIs version numbers. This page explains:

  • Where to find the version number

  • Which changes we can make at any time

  • Which changes need a new version

  • How much notice you get before an old version stops working

This page is about Our APIs, which start with https://api.awin.com/public. It doesn’t cover the Legacy APIs, which start with https://api.awin.com.

At a glance

Question

Answer

Where is the version number?

In the URL, straight after /public. For example, /v1/.

What is the first version?

v1

Do small updates change the URL?

No

Does adding a new field mean a new version?

No

Does removing a field mean a new version?

Yes

How much notice do I get before a version stops working?

At least 12 months.

How will I find out?

On this help site, through our usual customer messages, and in the API’s replies.

Where to find the version number

Every API URL has a version number straight after the main web address:

https://api.awin.com/public/v1/...

Our APIs start at v1. Only the main version number appears in the URL. Smaller updates don’t change the number, because you don’t need to do anything when they happen.

Because the version is part of the URL, you choose which version to use. Your tool keeps using the same version until you decide to move to a new one.

Changes we can make at any time

Some changes won’t break a tool that was built using our documentation. We can make these changes at any time, without a new version number:

  • Adding a new endpoint (a new URL you can send requests to)

  • Adding a new optional field to a reply

  • Adding a new optional query parameter or request field

  • Adding a new possible value to a field that only allows certain values

  • Fixing our documentation, descriptions, and examples

How to make sure these changes don’t break your tool

Build your tool so it can cope with these changes:

  • Ignore fields it doesn’t recognize. New fields may appear in replies.

  • Handle new values gracefully. Some fields only allow certain values. If a new value appears, your tool shouldn’t treat it as an error.

  • Don’t rely on the order of fields. Fields in a reply may appear in a different order.

Changes that need a new version

A breaking change is a change that would stop a tool built with our current documentation from working. We never make breaking changes to an existing version. Instead, we release them in a new version, such as v2. The old version keeps working until its end date.

Examples of breaking changes:

  • Removing or renaming an endpoint, field, or parameter

  • Changing the type or format of a field (for example, from a number to text)

  • Making an optional field or a parameter required

  • Making a field that always appeared in a reply sometimes missing

Note

The last example is easy to miss. If our documentation says a field always appears in a reply, your tool can rely on it. If we change that field so it’s sometimes missing, that counts as a breaking change, even though we didn’t remove anything.

How we retire an old version

When we plan to stop supporting an endpoint or a whole version, we follow the same steps every time:

We mark it as deprecated. Deprecated means it’s being phased out. Our documentation shows this and tells you what to use instead.

  1. We add a warning to the API’s replies. From then on, every reply includes two extra headers:

    • Deprecation shows that the endpoint is being phased out.

    • Sunset shows the date it will stop working.

  2. We tell you. We tell customers through this help center and through our usual customer messages. The headers aren’t the main notice. They’re there so your tool can spot the change on its own, even if nobody has read our message yet.

  3. We give you at least 12 months. There are always at least 12 months between marking something as deprecated and turning it off.

  4. We turn it off. After the sunset date, the endpoint or version may stop working.

Here’s an example of a reply from a deprecated endpoint (the date is just an example):

HTTP/1.1 200 OK
Deprecation: true
Sunset: Fri, 31 Dec 2027 23:59:59 GMT
Content-Type: application/json

Tip

Set up your tool to log or send an alert whenever it sees a Deprecation or Sunset header. That way, you have the full notice period to move to the new version.

Moving to a new version

When we release a new version:

  • The old and new versions both work until the old version’s sunset date.

  • Each endpoint’s page shows which version you’re reading about.

  • You choose when to move your tool to the new version. The old version keeps working until its sunset date.