API Versioning & Deprecation

Versioning

All Emofy Developer API endpoints live under a URI-major prefix:

https://api.emofy.net/api/v1/...

The version in the path (v1) is the major version. A new major (v2) is opened only when a breaking change ships — and only an operator-approved change may introduce one. While a new major is live, the previous major keeps running side-by-side for its support window.

Support window

Each major version is supported for at least 12 months after its successor becomes generally available. During that window the version may stop gaining new features, but it keeps receiving security fixes and its non-breaking behavior is preserved.

What counts as a breaking change

A change is breaking when it would invalidate an existing, correct integration. Concretely (and enforced mechanically in CI against the OpenAPI contract):

• removing an endpoint (path);
• removing a method on an endpoint;
• removing a field from a response;
• making a previously-optional request field required;
• changing a field's type, or removing a schema.

Additive changes — new endpoints, new methods, new optional fields, new schemas — are not breaking and ship within the current major. Write your integration to ignore unknown response fields so additive changes never break you.

Deprecation lifecycle

When an endpoint (or a whole major version) is on its way out, it moves through four stages:

1. Announcement — published here and in the changelog.
2. Header period (≥ 6 months) — every response carries the deprecation headers below, and the OpenAPI operation is marked deprecated: true (it renders struck-through in the API reference).
3. Sunset — the announced date by which you should have migrated.
4. 410 Gone — after sunset, the endpoint responds with 410.

Deprecation headers

A deprecated endpoint returns three headers on every response:

Deprecation: @1767139200
Sunset: Thu, 31 Dec 2026 23:59:59 GMT
Link: <https://docs.emofy.net/docs/developer/versioning>; rel="deprecation"

Reacting programmatically

The official SDK surfaces deprecations without you parsing headers. Pass an onDeprecation callback and you get notified once per deprecated endpoint:

import { createEmofyClient } from "@emofy/dev-sdk";

const client = createEmofyClient({
  apiKey: process.env.EMOFY_API_KEY!,
  baseUrl: "https://api.emofy.net/api/v1",
  onDeprecation: (info) => {
    console.warn(
      `Endpoint ${info.path} is deprecated; sunset ${info.sunsetAt}. See ${info.docsUrl}`,
    );
  },
});

The default behavior (no callback) is a single console.warn per endpoint.

SDK versioning

The @emofy/dev-sdk major version tracks the API major: @emofy/dev-sdk@1.x.y targets /api/v1. Pin ^1 and you will never receive a breaking API change through an SDK upgrade.

When v2 opens, @emofy/dev-sdk@2.0.0 is published; the 1.x line keeps receiving maintenance releases for the v1 support window.