Deprecating endpoints in the Oyster REST API

When we need to retire an endpoint, we follow a predictable lifecycle so you have time to migrate before it stops working. This guide describes the signals you should watch for and how to consume them.

Lifecycle

An endpoint goes through three stages:

1. Active — the endpoint works as documented and returns no deprecation signals.
2. Deprecated — the endpoint still works, but we are signalling that it will be removed. You'll receive deprecation headers and body metadata on every response. This window is typically 180 days from the deprecation date to the sunset date.
3. Sunset — the endpoint no longer functions. Requests return 400 Bad Request with:

{
  "errors": [
    { "message": "This endpoint has been sunset and is no longer supported." }
  ]
}

Response headers

During the deprecated stage, we add three standard HTTP headers (following RFC 9745 and RFC 8594):

These headers are attached to every response (including successful ones) for deprecated endpoints, so you can detect deprecations in your HTTP client without parsing the body.

Response body metadata

We also include a deprecation object under the top-level meta field of the JSON response:

{
  "data": { "...": "..." },
  "meta": {
    "deprecation": {
      "at": "2025-11-01T00:00:00Z",
      "sunset": "2026-04-30T00:00:00Z",
      "link": {
        "rel": "deprecation",
        "url": "https://docs.oysterhr.com/..."
      }
    }
  }
}

Versioning

Deprecations are scoped to an API version (e.g. v0.1, v1). An endpoint that is deprecated in v0.1 may still be fully supported in a newer version; the migration docs linked from the Link header / meta.deprecation.link will tell you what to call instead.

Recommended client behavior

• Log or alert whenever you see a Deprecation or Sunset header, including the route that returned it — don't wait for the sunset date to notice.
• Follow the Link / meta.deprecation.link.url to find the replacement endpoint and migration steps.
• Plan your migration using the Sunset value. After that date the endpoint returns 400 and your integration will break.
• Treat deprecation as advisory, not breaking — during the deprecation window the endpoint's contract is unchanged.