API Deprecations¶
This page describes how EarthRanger marks API endpoints as deprecated, the HTTP
headers we emit to advertise that status, and how clients should react. It is
the source of truth for the deprecation policy across /api/v1.0/.
How to detect a deprecated endpoint¶
A deprecated endpoint behaves exactly like its non-deprecated form, but every response carries three additional headers. Clients integrating with EarthRanger should inspect these headers and react accordingly.
Header |
RFC |
Meaning |
Example value |
|---|---|---|---|
|
RFC 9745 |
Structured-field Date item ( |
|
|
RFC 8594 |
HTTP-date (IMF-fixdate, RFC 7231 §7.1.1.1) for when the endpoint will be removed. Treat this as the drop-dead date. |
|
|
RFC 8288 |
One header carrying two comma-separated link values: |
|
The Deprecation value is always less than or equal to Sunset. Clients that
only check one header should check Deprecation for “is this deprecated?” and
Sunset for “when must I be off this?”.
Lifecycle¶
EarthRanger API endpoints move through three phases:
Active. No deprecation headers are emitted. The endpoint is supported and may evolve in backwards-compatible ways.
Deprecated. The endpoint still works exactly as before. The three headers above are attached to every response.
Sunsetis set at least six months in the future, giving integrators time to migrate. TheLinkheader (when present) names the successor endpoint.Removed. After the
Sunsetdate the endpoint may be removed from the URL configuration. A request to a removed endpoint typically returns404 Not Found; in some cases the route may be retained briefly and return410 Gone. EarthRanger does not automatically convert a deprecated endpoint into a 410 at the sunset boundary — removal happens in a subsequent release.
How to migrate¶
Read the
Linkheader to find the canonical successor path. This is the replacement we recommend.Consult the per-endpoint API reference for any payload or semantic differences. Successor endpoints are not guaranteed to be drop-in replacements — schemas, query parameters, and pagination behaviour may have changed.
If you operate a long-running client (mobile app, integration service, research notebook scheduled to run for months), parse the
Sunsetheader at deploy time and surface an alert when it falls inside your maintenance horizon.Once you have switched all callers to the successor, you can stop monitoring the deprecated endpoint.
A minimal client-side check looks like this:
response = http.get("/api/v1.0/features/")
if response.headers.get("Deprecation"):
successor = parse_link_header(response.headers.get("Link"))
sunset = parse_http_date(response.headers["Sunset"])
log.warn("endpoint is deprecated; sunset=%s; use %s", sunset, successor)
Current deprecations¶
Each deprecation runs on its own schedule — check the Deprecated on and
Sunset columns per row rather than assuming a single fleet-wide date pair. The
Deprecation and Sunset headers emitted by an endpoint always match its row
below. All paths are rooted at /api/v1.0/ unless otherwise noted.
Deprecated path |
Successor path |
Deprecated on |
Sunset |
|---|---|---|---|
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-05-23 |
2027-05-23 |
|
|
2026-07-31 |
2026-10-15 |
|
|
2026-07-31 |
2026-10-15 |
|
|
2026-07-31 |
2026-10-15 |
The successor Link header emitted by each endpoint uses the exact target path
listed above (with <id> and <value> left as placeholders).
Version 1 Event Types¶
The three event-type rows above are part of a wider retirement of version 1
Event Types. /api/v1.0/activity/events/eventtypes/ and its detail route only
ever return, and only ever accept, version: 1 event types; the v2.0 surface is
where v2 event types live and where new work should target. The successor
endpoints are keyed by the event type’s value (its slug) rather than its UUID,
although /api/v2.0/activity/eventtypes/<uuid>/ is also accepted today.
/api/v1.0/activity/events/schema/eventtype/<value>/ serves both versions, but
it is part of the v1 surface and is deprecated in full: use the v2 schema action
for v2 event types.
All three endpoints emit these headers unconditionally, on every response, regardless of what the response body contains.
Two related v1.0 routes are not deprecated:
/api/v1.0/activity/events/eventtypes/<id>/rank— ranks event types of both versions and has no v2.0 equivalent./api/v1.0/activity/events/eventtypes/icons/…— shared icon infrastructure, not version-specific.