Making /api/v1 a stable contract: deprecation lifecycle, schema snapshots, and a support window

[Apoorvgarg-creator]

Making /api/v1 a stable contract: deprecation lifecycle, schema snapshots, and a support window

This discussion proposes an API stability policy for Observal. It defines what counts as a breaking change, what contributors would be asked to do before opening a PR that touches an API surface, what reviewers would be asked to check before approving one, and a phased engineering plan to back the discipline up with tooling.

Nothing in this document is final. Where this document takes a position, it is a starting position. If you disagree with any of the rules, the lifecycle, the support window, or the phasing, please push back in the comments. The goal is to land a policy the community has shaped, not one handed down.

The same rules would apply to:

• REST endpoints under /api/v1/...
• The GraphQL schema served at /api/v1/graphql
• Response shapes consumed by the CLI, the web frontend, and any third-party integrations
• The /api/v1/config/version handshake endpoint (treated as load-bearing)

A companion document, discussion #965, covers schema migrations and CLI/server upgrade safety. The two policies are siblings.

Why this matters

Observal is self-hosted. One CLI release fans out across many operators, on many server versions, with no central control. The cost of a silent breaking change is therefore disproportionately high: a single removed field can break many CLIs in the field, and there is no way to push a hotfix to them.

The proposal rests on three premises. These are starting positions; if any of them feel wrong, that is exactly the kind of feedback worth raising in the comments.

1. Inside /api/v1, every removal or rename is treated as breaking. Additive changes are safe. Anything else is not.
2. Breaking changes ship with a deprecation window, not as a cliff. A field that goes away would first be marked deprecated for at least one minor release, with a documented sunset date.
3. Contributors and reviewers share responsibility. Awareness is the first line of defense; CI is the second.

What counts as a breaking change

If you are unsure whether your change is breaking, assume it is and read this section.

These are breaking:

• Removing a field from a response model
• Renaming a field (this is a remove plus an add)
• Changing a field's type (e.g. int to string, nullable to not-null)
• Narrowing a type (e.g. str to Literal["a", "b"])
• Removing or renaming an enum value
• Removing an endpoint
• Changing a status code (e.g. 200 to 201, 404 to 200)
• Adding a required request field
• Tightening validation on an existing request field
• Changing the meaning of an existing field (e.g. units, timezone, encoding)
• Removing or renaming a GraphQL field, argument, or type

These are additive (safe):

• Adding a new endpoint
• Adding a new optional response field
• Adding a new optional request field
• Adding a new enum value, as long as clients are documented as ignoring unknown values
• Adding a new GraphQL field with a default

These are gray-zone (require explicit reviewer sign-off):

• Changing the order of items in a list response
• Changing pagination defaults
• Changing the format of an ID (e.g. UUID v4 to v7)
• Adding rate limits or making them stricter
• Changing error message text that a client might parse

What this would ask of contributors

Before opening a PR that touches any API surface listed above, the proposal would ask you to:

1. Run the breaking-change checklist in the section above. If your change is breaking, you must follow the deprecation lifecycle, not remove directly.

2. For a removal or rename: keep the old field in place, mark it deprecated, schedule removal for at least one minor release later. The PR that deprecates and the PR that removes must be separate, in separate releases.

3. Bump MIN_CLI_VERSION in observal-server/config.py if your change removes or renames a field the CLI consumes. This is the floor below which the server refuses old CLIs.

4. Update the OpenAPI snapshot (once Phase 3 ships). The CI diff is your contract-change receipt.

5. Add a CHANGELOG entry under the API contract subsection. Format: [deprecated] or [removed] or [added], then the endpoint and field, then the removal target version. Example:

   ## 0.10.0 — 2026-06-01
   ### API contract
   - [deprecated] GET /api/v1/agents.legacy_score — remove in 0.12.0, use quality_score
   - [added] GET /api/v1/agents.quality_score
   

6. Cross-link discussion #965 if your change also touches a database schema. Schema and API changes often move together; they need to be reviewed together.

What this would ask of reviewers

When reviewing a PR that touches an API surface, the proposal would ask you to explicitly check (and say so in the review):

1. Read the diff against the breaking-change list above. If anything matches, the PR must follow the deprecation lifecycle.
2. Look for hidden breaks. Renames disguised as refactors (agent_id to agentId), type changes from auto-inferred Pydantic models, GraphQL field removals that look like file deletions.
3. Confirm MIN_CLI_VERSION is bumped if a CLI-consumed field is being removed in this PR.
4. Confirm the CHANGELOG entry exists and points to the right removal target.
5. For deprecations, confirm the @deprecated decorator (REST) or deprecation_reason (GraphQL) is wired so headers actually emit. A deprecation without the header is a deprecation in name only.
6. For schema/migration PRs, apply the rules in discussion #965 and AGENTS.md in addition to the rules above.
7. Block the PR if any of the above is missing. Do not "approve with comments" on API breakage. The cost of getting this wrong is paid by every operator in the field.

A PR that touches an API surface must have a review comment that says, in some form, "I checked the breaking-change list and CHANGELOG entry, this is [additive / deprecation / removal-of-previously-deprecated]." If that sentence is missing, the review is incomplete.

Proposed plan

Four phases. Each phase would ship independently. The phasing is a suggestion; alternative orderings are welcome in the comments.

flowchart TB
    P1[Phase 1: Process + AGENTS.md rules] --> P2[Phase 2: Deprecation lifecycle in code]
    P2 --> P3[Phase 3: CI enforcement]
    P3 --> P4[Phase 4: v2 preparation]

Loading

Phase 1: Process and rules in writing

Status: this discussion + the AGENTS.md section landed on the same commit.

• Breaking-change definition: this document.
• Contributor and reviewer checklists: this document.
• AGENTS.md section "Schema and CLI/server upgrade safety": the rules AI reviewers and contributors must follow.
• PR template: a checkbox row that asks "does this PR touch an API surface? If yes, did you follow the deprecation lifecycle, bump MIN_CLI_VERSION if needed, and add a CHANGELOG entry?"
• README and CONTRIBUTING.md updated to point to this document.

Phase 2: Deprecation lifecycle in code

Goal: a removal stops being a cliff and becomes a ramp.

1. Bidirectional version handshake. Extend /api/v1/config/version (additively) with schema_revision. Ship a compat.json inside the CLI wheel declaring min_server_version and min_schema_revision. The CLI warns when the server is too old, not only when the CLI is too old.

2. Standards-compliant deprecation headers (RFC 8594). Every response that includes a deprecated field carries:

   Deprecation: true
   Sunset: Wed, 01 Jan 2027 00:00:00 GMT
   Link: <https://docs.observal.dev/api/migrations#legacy_score>; rel="deprecation"
   

3. Per-field decorator for REST. A @deprecated_field(name, since, removed_in, replacement=None) decorator on FastAPI response models. The decorator emits the field as usual and registers it for header emission. Example:

   class AgentResponse(BaseModel):
       id: UUID
       name: str
       legacy_score: float | None = Field(
           default=None,
           json_schema_extra={"deprecated": True, "removed_in": "1.0.0"}
       )
       quality_score: float | None = None

4. GraphQL field deprecation. Use Strawberry's deprecation_reason consistently. Same lifecycle as REST.

5. Soft-warning flow:

sequenceDiagram
    participant Dev as Maintainer
    participant Server
    participant CLI as Old CLI in the field

    Note over Dev,Server: Release N: deprecate
    Dev->>Server: Mark field deprecated, removed_in=N+2
    CLI->>Server: GET /api/v1/agents
    Server-->>CLI: Field present + Deprecation/Sunset/Link headers
    CLI->>CLI: Surface as observal doctor warning

    Note over Dev,Server: Release N+2: remove
    Dev->>Server: Delete field, bump MIN_CLI_VERSION
    CLI->>CLI: Operator has already been warned twice

Loading

Phase 3: CI enforcement

Goal: the test suite catches breaks before review even starts.

1. OpenAPI contract snapshot. Commit tests/contracts/openapi.snapshot.json. CI fails any PR that changes the shape unless the snapshot is updated in the same PR. Snapshot updates surface the contract change in review.
2. GraphQL SDL snapshot. Commit tests/contracts/schema.graphql. Same idea.
3. MIN_CLI_VERSION enforcement test. If the OpenAPI diff is non-additive, the test fails unless MIN_CLI_VERSION was bumped in the same PR.
4. Cross-version integration matrix. CI runs (current CLI) against (previous server release container), and vice versa. Both must pass for green.

flowchart LR
    PR[PR opened] --> O[OpenAPI snapshot diff]
    O -- additive --> Pass1[Pass]
    O -- breaking --> M{MIN_CLI_VERSION bumped + CHANGELOG entry?}
    M -- yes --> Pass2[Pass]
    M -- no --> Fail[Block merge]

Loading

Phase 4: v2 preparation

We will not pre-build v2. We will define the trigger and the procedure now so when v2 is needed, it is a known operation.

v2 trigger criteria (any one of):

• An auth model change that cannot be retrofitted into v1
• A pagination or ID format change across the whole API
• A protocol switch (e.g. REST to gRPC) for a meaningful surface

v2 procedure when triggered:

1. Mount /api/v2/... alongside /api/v1/.... Both serve traffic.
2. Freeze v1. Only security fixes from this point.
3. CLI negotiates via Accept-Version: 2, falls back to v1 on 406.
4. Emit Sunset headers on v1 with a minimum 6-month horizon.
5. observal doctor surfaces the v1 sunset to operators as a recurring warning.

Starting positions on the open questions

A few items came up during the audit that need a working answer. The table below records a starting position for each, with the reasoning, so the discussion has something concrete to react to. None of these are settled. If you have a stronger argument for a different answer, please raise it in the comments.

Question	Starting position	Why
Should MIN_CLI_VERSION be per-endpoint or global?	Global, for now	A per-endpoint floor adds complexity. Worth revisiting if a real case appears where it matters.
Do we version OTLP ingest endpoints (/v1/traces, /v1/logs, /v1/metrics)?	Out of scope	Those follow the OpenTelemetry spec, not ours.
Do we snapshot the GraphQL schema or the introspection result?	Schema SDL	It is the source of truth; introspection is a derived view.
Pre-1.0, does this policy apply strictly?	Yes	"We are pre-1.0 so we can break things" is how field CLIs end up broken. Open to a softer rule if the community prefers.
What is the support window?	N to N-1	CLI version N supported by server N and N-1. N-2 is friendlier but adds compat code; happy to hear arguments for it.

Where the rules live

• This document: the contract definition, contributor checklist, reviewer checklist, and roadmap.
• AGENTS.md section "Schema and CLI/server upgrade safety": the codified rules that human and AI reviewers apply.
• Discussion #965: the sibling policy for database schema migrations and CLI/server upgrade safety.
• CHANGELOG.md API contract subsection (going forward): the audit trail of what we deprecated, added, and removed, per release.

Feedback we are specifically looking for

This is where your input is most useful:

1. Is the breaking-change list right? Anything missing, anything too strict, anything that should move between buckets?
2. Is the deprecation window long enough? One minor release is the proposal. Some projects use two, some six months. What feels right for Observal's release cadence?
3. Is the contributor / reviewer checklist realistic? Is there a step that would create more friction than value?
4. Are the phases in the right order? Phase 1 is process. Phase 2 adds tooling. Phase 3 adds CI. Some communities prefer to land CI enforcement first so the process has teeth from day one.
5. Anything in the "starting positions" table you would answer differently?

If the community lands on this

Three small things contributors and reviewers could start doing immediately, even before Phases 2 and 3 ship:

• Contributors: read the breaking-change definition; run the checklist on your next API-touching PR.
• Reviewers: leave the explicit "I checked the breaking-change list" comment on PRs touching observal-server/api/, observal-server/schemas/, or any GraphQL resolver.
• Anyone: if you spot an existing violation in main, open an issue with an api-contract label so we can track it.

The discipline is the deliverable. The tooling in Phases 2 and 3 makes the discipline durable. The community shaping this policy is what makes it stick.

[Haz3-jolt]

Agree with all, maybe a little less on some fronts? Too much backwards compat can mess things up.

[Apoorvgarg-creator]

yes, If the things feel overwhelming here, let's discuss on what we can trim down

[Pyasma]

LGTM, agree with most of them