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 |
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.
We add a warning to the API’s replies. From then on, every reply includes two extra headers:
Deprecationshows that the endpoint is being phased out.Sunsetshows the date it will stop working.
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.
We give you at least 12 months. There are always at least 12 months between marking something as deprecated and turning it off.
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/jsonTip
Set up your tool to log or send an alert whenever it sees a
DeprecationorSunsetheader. 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.