Bloxwap API versioning and deprecation policy

This is the contract for the Bloxwap public read API. It exists so that an integration can tell, in advance, what kinds of change can happen underneath it and how much warning it will get.

Versions

The current version is v1, served at https://bloxwap.com/api/v1/…. Integrate against that path.

The unversioned /api/… paths serve the identical handlers and will keep working — they are what the Bloxwap app itself calls — but they carry no version guarantee. A new integration should prefer /api/v1/.

What can change within a version

Additive changes ship at any time, without notice, and are not considered breaking:

• New endpoints.
• New optional query parameters.
• New fields on an existing response.
• New values in a field documented as an open set, such as a source.

Parse defensively: ignore fields you do not recognise, and do not treat an unfamiliar enum value as an error. A client that rejects unknown fields will break on a change this policy considers safe.

What will not change within a version

• An existing field will not be removed, renamed, or change type.
• A required parameter will not be added to an existing operation.
• Accepted input will not be narrowed.
• An operationId will not be reused for a different operation.

Anything that would break a correct v1 client ships as /api/v2/ instead, and v1 continues to answer.

How a retirement is signalled

If an operation or a version is ever retired, in this order:

1. Its responses begin carrying a Deprecation header (RFC 9745) giving the date the deprecation took effect, and a Sunset header (RFC 8594) giving the date it will stop answering.
2. The operation is marked deprecated: true in /openapi.json, and this page describes the replacement.
3. Those headers are served for at least 90 days before the endpoint stops answering.

Nothing disappears without that notice having been served first. If you poll one endpoint, watching for a Sunset header on the response is sufficient to catch a retirement in time.

Questions

support@bloxwap.com, or the developer overview.