API Versioning and Deprecation

The Wraps Platform API is versioned in the URL. The current version is served at https://api.wraps.dev and described by the OpenAPI document, whose info.version names the version you are reading.

A breaking change ships as a new version at a new path. The old version keeps working for the notice period below — it is never changed underneath you.

These ship only in a new version:

• Removing an endpoint, or changing its path or method
• Removing a field from a response, or changing its type
• Adding a required request field, or making an optional one required
• Narrowing an accepted value — tightening a format, dropping an enum member
• Changing the status code or error `code` a given failure returns
• Changing authentication or the scopes an endpoint requires

These ship into the current version at any time, so build a client that tolerates them:

• Adding a new endpoint
• Adding an optional request field
• Adding a field to a response — always parse responses permissively
• Adding a new value to an enum you only read (never one you match exhaustively on)
• Adding a response header
• Changing the prose of an `error` message, while its `code` stays put

A deprecated endpoint keeps working and starts announcing itself on every response.

The same endpoints are marked deprecated: true in the OpenAPI document, so a generated client sees it at build time rather than at runtime.

Deprecations are announced in the changelog and emailed to organization owners. Nothing is removed without a Sunset date having passed.

• Read code, not error, when branching on a failure. The code values are stable and enumerated in the OpenAPI document; the prose is not.
• Ignore response fields you do not recognize instead of rejecting the response.
• Log the Deprecation and Sunset headers if they appear. That is the only signal that arrives before something you depend on stops working.
• Pin the OpenAPI document you generate clients from, and re-generate deliberately.