API Versioning

ADR-0015 establishes URI versioning for the public REST API and buf breaking-change detection for internal gRPC contracts.

Versioning Table

Public REST API

The major version is encoded in the URI path (/v1/). A major version is a stable, long-lived contract.

Backwards-Compatible Evolution Within a Major Version

The following changes are additive and are allowed without a version bump:

• New optional request fields (ignored by older clients).
• New response fields (ignored by older clients using strict deserialization is a client bug, not ours).
• New endpoints.
• New enum values in response fields (clients must handle unknown values gracefully).

The following changes are breaking and require /v2/:

• Removing or renaming a field.
• Repurposing a field (same name, different semantics).
• Tightening validation (a value previously accepted now returns 400).
• Changing a field’s type.
• Removing an endpoint.

Deprecation Process

When an endpoint or field is deprecated:

1. Add Deprecation and Sunset HTTP response headers with the planned removal date.
2. Mark it in gen/openapi/bitvault.yaml with deprecated: true and an x-sunset extension.
3. Announce with at least one major version overlap: /v1 remains available until the sunset date after /v2 ships.

Public API Freeze Gate

/v1 declared stable is the gate for the React Native mobile app (P5 / NG4). The mobile client cannot ship against a moving contract. Once the freeze is declared, /v1 field additions are still allowed; removals require a /v2 process with a minimum 6-month sunset window.

Internal gRPC Contracts

Internal gRPC is governed by buf breaking-change detection in CI.

Rules enforced:

• Field additions and new RPCs are allowed.
• Field removals, renumbers, or type changes fail the pipeline.
• Reserved tags (reserved 5; in proto) are required for deleted fields to prevent silent renumber reuse.
• Never reuse a field number, even for a “compatible” type.

The buf check runs as buf breaking --against .git#branch=main in every PR.

:::tip OpenAPI The generated OpenAPI spec (gen/openapi/bitvault.yaml) is the authoritative reference for the public REST API. It is generated from the proto definitions via task gen — never edit it manually. Any manual edit will be overwritten on the next task gen run. :::