Benjamin_Boenisch/breakpilot-compliance
1
0
Fork 0
Code Issues 24 Pull Requests Actions Packages Projects Releases Wiki Activity

Establish API versioning and pagination response standard #22

New Issue
Open
opened 2026-04-20 09:37:17 +00:00 by sharang · 0 comments
sharang commented 2026-04-20 09:37:17 +00:00
Owner
Copy Link
Copy Source

Problem

API responses have no version field. When the schema changes, clients have no way to detect or handle the difference. Combined with missing pagination metadata (#13), clients cannot build reliable pagination UI.

Required Actions

  1. Add api_version: str to all response schemas (current value: "v1")
  2. Adopt PaginatedResponse[T] (from #13) as the standard for all list endpoints
  3. Document the versioning policy in AGENTS.python.md:
    • Additive changes (new optional fields) → no version bump
    • Breaking changes (removed/renamed fields) → new route version (/api/v2/)
  4. Add a contract test that diffs live /openapi.json against tests/contracts/openapi.baseline.json — fails CI on breaking changes
  5. Update openapi.baseline.json intentionally when a breaking change is approved

Acceptance Criteria

## Problem API responses have no version field. When the schema changes, clients have no way to detect or handle the difference. Combined with missing pagination metadata (#13), clients cannot build reliable pagination UI. ## Required Actions 1. Add `api_version: str` to all response schemas (current value: `"v1"`) 2. Adopt `PaginatedResponse[T]` (from #13) as the standard for all list endpoints 3. Document the versioning policy in `AGENTS.python.md`: - Additive changes (new optional fields) → no version bump - Breaking changes (removed/renamed fields) → new route version (`/api/v2/`) 4. Add a contract test that diffs live `/openapi.json` against `tests/contracts/openapi.baseline.json` — fails CI on breaking changes 5. Update `openapi.baseline.json` intentionally when a breaking change is approved ## Acceptance Criteria - OpenAPI baseline test runs in CI and is non-skipped - All list endpoints return `PaginatedResponse` - Depends on: #13
sharang added this to the M4: Testing & Contract Stability milestone 2026-04-20 09:37:17 +00:00
sharang added the data-integrityseverity: medium labels 2026-04-20 09:37:17 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
config
Env vars, secrets management, startup validation
 data-integrity
Transactions, indexes, pagination
 frontend
Next.js, client-side concerns
 observability
Logging, audit trails, health checks
 reliability
Error handling, retries, circuit breakers
 security
Auth, secrets, injection, tenant isolation
 severity: critical
System-level risk, data breach or full outage
 severity: high
Significant risk, must fix before go-live
 severity: medium
Important but not blocking go-live
 testing
Test coverage, integration tests
No Label data-integrity severity: medium
Milestone
No items
No Milestone M4: Testing & Contract Stability
Projects
Clear projects
No project
Assignees
Clear assignees
sharang (Sharang Parnerkar) Benjamin_Boenisch
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Benjamin_Boenisch/breakpilot-compliance#22
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?