Skip to content

Public API policy

API Versioning And Deprecation Policy

The canonical lifecycle contract for Jovie's public artist API. It explains how versions change and how genuine retirement will be signaled.

Versioning

Jovie uses URL versioning. The current public artist API is /api/v1, served from https://jov.ie. Additive fields and backward-compatible changes remain within the active version; breaking request or response changes receive a new major URL version.

Deprecation And Sunset Signals

Version v1 is active and is not deprecated. No retirement date is scheduled. Current v1 responses intentionally omit Deprecation and Sunset headers; the discovery link to this page is policy documentation only and does not retire the active version.

Before a genuinely deprecated version is removed, Jovie will publish migration guidance on this page and signal the change with the RFC 9745 Deprecation header and a Link relation to the guidance. When a dated retirement window is announced, responses will also carry an RFC 8594 Sunset HTTP-date. These signals are emitted only for the affected deprecated version.

Machine-readable Contract

The OpenAPI 3.1 contract carries the same versioning policy in its x-jovie-versioning extension. The API reference covers request details, rate limits, and examples.