Skip to main content

API Lifecycle

This page defines the compatibility rules we want customers to rely on for the supported /api/v1 API.

Stability goal​

The scoped /api/v1 API is the supported integration surface for StatiBeat.

Our goal is:

  • additive changes should not break existing clients
  • breaking changes should not be introduced silently
  • deprecated behavior should be announced before removal

Compatible changes​

These are intended to be safe without a version bump:

  • adding new endpoints
  • adding new optional response fields
  • adding new optional request fields
  • improving descriptions, examples, or metadata in the OpenAPI contract

Breaking changes​

These should be treated as breaking and planned deliberately:

  • removing endpoints
  • removing fields
  • changing field meaning or type incompatibly
  • making optional fields required
  • changing auth requirements incompatibly

Deprecation policy​

When an endpoint or field needs to be retired:

  • mark it as deprecated in the contract when possible
  • document the replacement path
  • communicate the expected removal timing in release notes or migration docs
  • avoid same-day removal of supported customer-facing behavior

Documentation policy​

  • the public OpenAPI artifact documents customer-supported routes
  • operational and security-sensitive routes can exist without being part of the public docs set
  • the full internal/admin contract may still be available for engineering use, but it is not the customer-facing promise