Developers

Deprecation and Sunset policy

How ChristianPicks versions the public catalog API, when endpoints are deprecated, and how Sunset headers work.

This page is the lifecycle policy for the ChristianPicks public catalog API. Agents should treat it as the canonical deprecation document. The OpenAPI document at /openapi.json points here through externalDocs and a rel="deprecation" Link header.

Current status

The catalog API is version 1.0.0. No public discovery endpoints are deprecated. No catalog route currently sends a Sunset date. Stable surfaces include the site manifest, /api/v1, product and business lookup, batch lookup, Ask ChristianPicks, anonymous OAuth registration, MCP, and the well-known discovery files.

What deprecated means

An operation marked deprecated: true in OpenAPI still works. We will also list it on this page. When a removal date is known, responses for that operation include:

  • Deprecation (RFC 9745) with the date we marked the operation obsolete
  • Sunset (RFC 8594) with the date we plan to remove it
  • Link: <https://christianpicks.com/deprecation>; rel="deprecation"

We do not send Sunset dates on healthy, current endpoints. A missing Sunset header means the operation is current.

Notice window

Breaking changes to the public catalog API get at least 12 months of notice before removal, unless a change is required for security or legal compliance. Additive fields, new endpoints, and new optional headers can ship without a Sunset date.

GET /api/v1 is an alias of the current catalog API. We will not remove /api or /api/v1 without following this policy.

How to stay current

  1. Read OpenAPI and check info.version plus any deprecated flags.
  2. Recheck this page, or the Markdown copy at /deprecation.md.
  3. Watch Deprecation and Sunset headers on the affected routes.
  4. Prefer documented fields over undocumented ones.

Questions: see developer resources or email [email protected].