Skip to main content

Versioning

The Mocart API is versioned in its path — everything documented here lives under /api/public/v1. Within that version, the compatibility promise is:

Additive changes can happen anytime, without notice​

A new endpoint, a new optional request field, a new response field, a new enum value on a response, or a new header can appear at any time, without a deprecation notice. This is safe because of one rule your integration must follow:

Ignore fields you don't recognize. Don't validate a response strictly against a fixed set of fields, and don't treat an unrecognized field as an error. A response you don't fully understand today may simply be carrying a field a future integration will use.

If your client validates responses against a schema of its own, keep that schema open on the response side — closed on the way in (what you send) is fine and encouraged, closed on the way out (what you accept back) will eventually break on a perfectly normal, additive change.

Breaking changes only ship as a declared, dated deprecation​

A change is breaking if it does any of the following to something already published:

  • Removes or renames an operation, a path, a response field, or an enum value.
  • Adds a required request field, or narrows an existing request field's accepted values.
  • Changes a field's type or format.
  • Changes an error's code or HTTP status for a case that already had one.

None of these ship silently. A breaking change is announced with:

  • A Deprecation header (RFC 9745) on every affected operation, from the day it's announced.
  • A Sunset header (RFC 8594) naming the date the old behavior stops.
  • At least 90 days between announcement and sunset.
  • An entry in the changelog describing the change and both dates.

Between the announcement and the sunset date, both the old and new behavior are documented, and the headers above tell you which operations are affected and when the clock runs out. After sunset, the new behavior is simply the behavior — there's no further notice.

Why there's no date-pinned version scheme​

Some APIs (Stripe, for example) let you pin a request to a specific calendar date and receive that date's exact response shape indefinitely. Mocart doesn't do this within /v1 — it would mean maintaining a translation layer between every pinned date and the current implementation, indefinitely, for every breaking change ever made. The additive-by-default promise plus a genuine 90-day notice window covers the common case (you have time to adapt) without that ongoing cost. A date-pinned scheme could still be layered on inside /v1 later without breaking anyone currently integrated — nothing here forecloses it.

Keep up with changes​

Watch the changelog for both additive changes worth knowing about and every declared breaking change, with its announcement and sunset dates.