Skip to content

Versioning and deprecation

/api/v1/ is stable. LuciBook makes additive changes without a version bump; a breaking change only ever ships in a new major version path.

What is NOT a breaking change

You must tolerate all of these without treating them as an error:

  • A new field appearing in a response.
  • A new endpoint.
  • A new optional request parameter.
  • A new enum value appearing in a response field.

What IS a breaking change (D-C1-05)

  • Removing or renaming a field, path, or query parameter.
  • Removing or renaming an enum value accepted in a request.
  • Changing a field's type or semantics.
  • Tightening validation on an existing field.
  • Changing an error code for an existing failure mode.

Deprecation

A breaking change is announced at least 12 months before it takes effect (enforced: the sunset date must be at least 365 days after the announcement date), via both of:

  1. An entry in the changelog.
  2. Response headers on the affected endpoint, appearing as soon as the deprecation is registered, on every /api/v1/ request that hits it:
    • Deprecation: @<unix epoch> — RFC 9745, the announcement date as a Unix epoch timestamp.
    • Sunset: <IMF-fixdate> — RFC 8594, the date the endpoint stops working.
    • Link: <https://developer.lucibook.co.uk/changelog/#…>; rel="sunset"; type="text/html" — points at the changelog entry for this deprecation.

Watch the changelog or the response headers — either tells you everything you need to migrate before the sunset date. There is no e-mail notification today; watching the headers or the changelog is currently the only way to find out.

Currently deprecated endpoints

Deprecation calendar

No endpoints are currently deprecated.