Skip to main content

Deprecation timelines

How we mark an endpoint or version as on its way out — and what you should do when you see the signal.

:::note Current status No endpoint under /api/v1/ is currently deprecated. This page describes how a deprecation will be signalled when one occurs. The signalling mechanism (response headers) is implemented in our backend; it just isn't being applied to any external endpoint right now. :::

The deprecation signals​

When an endpoint becomes deprecated, the response carries one or two HTTP headers.

1. The Deprecation response header​

Deprecation: true

Tells you the endpoint is deprecated. Plain true value — once you see it, plan a migration.

(See RFC 9745 for the formal spec.)

When a replacement exists, the deprecated endpoint advertises it:

Link: </api/v1/traffic/sites/42>; rel="successor-version"

Follow the link to find the migration target. The URL is reversed to match the same resource you were asking about — so for path-parameterised routes like /devices/{serial}/..., the successor-version link substitutes your specific serial into the new path.

A note on Sunset​

Some APIs also emit a Sunset response header (RFC 8594) carrying the date the endpoint will stop working. The MyTrafficData API does not currently emit Sunset — we may add it in a future release.

What gets deprecated​

  • An entire major version (e.g., /api/v1/ deprecated when /api/v2/ ships).
  • A specific endpoint (rare — usually only happens if a replacement was added inside the same major).

In both cases, the same Deprecation + Link headers signal the change.

Detection recipe​

Have your monitoring read response headers and flag deprecation as a low-priority alert:

Python — detect deprecation
import requests

r = requests.get("https://mytrafficdata.com/api/v1/...", headers=headers)

if r.headers.get("Deprecation") == "true":
    successor = r.headers.get("Link")  # may carry rel="successor-version"
    log.warning(
        "Calling deprecated endpoint",
        extra={"successor": successor, "url": r.request.url},
    )
JavaScript — same idea
const r = await fetch(url, {headers});
if (r.headers.get("Deprecation") === "true") {
  console.warn("Deprecated endpoint", {
    successor: r.headers.get("Link"),
    url: r.url,
  });
}

Treat it like a build warning: not blocking, but worth fixing on your schedule.

Summary checklist​

  • ✅ Watch for Deprecation: true and Link: rel="successor-version" headers.
  • ✅ Sunset is not currently emitted by this API.
  • ✅ Treat deprecation as planned work, not an emergency.
  • ✅ Currently no /api/v1/ endpoint is deprecated — this page is here so you know the contract when one is.