Skip to main content

API Lifecycle

Stability Levels​

Every endpoint in the API reference is annotated with one of the following stability levels:

LevelMeaningGuarantee
GAGenerally availableSupported under SLA. No breaking changes within a major version.
BetaPublic but evolvingBackward compatibility is best-effort. Breaking changes communicated 30 days in advance.
AlphaExperimentalMay change or be removed without notice. Not recommended for production. Off by default — opt in via request header.

Versioning​

The API version is embedded in the URL path: /v1/.... Breaking changes ship as a new major version: /v2/.... Both versions run in parallel for at least 12 months after a new major version is released. New non-breaking features land in the current major.

What counts as a breaking change​

  • Removing or renaming a field, endpoint, scope, or error code.
  • Changing a field's type, semantics, or required/optional status.
  • Tightening validation rules.
  • Changing default values that affect observable behaviour.

What does not count as a breaking change​

  • Adding new endpoints, fields, scopes, error codes, or event types.
  • Loosening validation.
  • Adding optional query parameters.

Design your clients to be tolerant of unknown fields (forward compatibility). Do not fail on unrecognised JSON properties.

Deprecation​

When an endpoint or field is deprecated:

  1. The response includes Deprecation: <date> and Sunset: <date> headers (RFC 8594).
  2. A migration guide is published in the developer portal.
  3. Email notifications are sent to all tenants with active usage of the deprecated path.

After the Sunset date, the endpoint returns 410 Gone.

Reading deprecation headers​

const response = await fetch('https://api.bcmlogic.com/v1/core/...', { /* ... */ });

const deprecation = response.headers.get('Deprecation');
const sunset = response.headers.get('Sunset');

if (deprecation) {
  console.warn(`This endpoint is deprecated as of ${deprecation}. Sunset: ${sunset}`);
}

Changelog​

A machine-readable changelog is available at https://api.bcmlogic.com/v1/changelog. The developer portal renders the human-readable view. Subscribe to the RSS feed for updates.