API versions and changes

The Signal API puts its version in the path: every endpoint today starts with /v1/. Code written against /v1/ keeps working for as long as /v1/ exists.

Changes within a version#

Within a version we only make changes that existing code can safely ignore:

• New endpoints.
• New optional request fields and query parameters.
• New fields in responses. Your code should ignore fields it does not know.
• New metrics, filters, brands and periods on a DataSet. These are data, not part of the API contract.
• New values in fields that name a type or status, such as a new error code. Your code should accept values it does not know.
• Corrections to descriptions and documentation.

Changes that need a new version#

These changes come only in a new version, such as /v2/, never within one:

• Removing or renaming an endpoint, a field or a parameter.
• Making an optional field or parameter required.
• Changing the type or meaning of a field.
• Changing how errors are reported.

An endpoint marked Deprecated in the reference still works in its version. It is left out of the next one.

When a new version is released#

• Both versions run side by side. The older one keeps working for a period after the new one is released, and we tell you in good time before it stops working.
• We tell you by email to your organization's administrators and with a notice on this site, both when a new version is released and before an older one stops working.
• The API reference shows the current version. Choose an older one in the API version list at the top of each reference page.

Where changes are listed#

Every change to the API is listed with its date in the API changelog.