Versioning & Deprecation

The REST API is versioned in the URL: every endpoint lives under https://api.edgaze.ai/v1. Within v1, Edgaze only makes changes that keep working integrations working. Changes that would break one are not made.

Changes that can happen at any time#

These are not breaking. Build your client to tolerate them:

• New endpoints, and new optional query parameters, headers, or body fields.
• New fields in response bodies, event data, and webhook bodies.
• New values in open sets: run event types, activity.kind, SSE event names, webhook event types, and error codes. Ignore a value you do not recognize, and handle an unknown error code like any other error with the same HTTP status.
• New response headers, and new HTTP statuses that an existing endpoint documents in the OpenAPI document.
• Changes to human-readable text, such as error message values and descriptions. Branch on error.code, never on message.
• Higher limits, for example a larger maximum page size.

Changes that are breaking#

These never happen within v1:

• Removing or renaming an endpoint, field, parameter, header, or enum value.
• Changing a field's type or meaning, or making an optional field required in a request.
• Returning a different error code or HTTP status for a condition that already had one.
• Requiring a scope that an endpoint did not require before.
• Lowering a documented limit that a working integration could already rely on.

How deprecations are announced#

When something in v1 is superseded, it is deprecated, not removed:

• The OpenAPI document marks it deprecated: true, and its docs page says what to use instead.
• The changelog announces it.
• Responses that used the deprecated feature carry a Deprecation header (RFC 9745) with the date it was deprecated, for example Deprecation: @1786492800, and a Link header with rel="deprecation" pointing at this page.

A deprecated v1 feature keeps working for as long as v1 is served.

The OpenAPI document's version#

info.version in the OpenAPI document follows semantic versioning within v1: the minor version goes up when something is added, and the patch version for corrections to the document itself. The major version stays at 1 for as long as the API path is /v1. Each version is published to the edgaze-ai/edgaze-openapi repository, so you can pin one.

Currently deprecated#