# REST API Contract Baseline

Purpose: define the contract-first rules for gateway_api and gateway_mobile endpoints.

---

## Contract Source of Truth

1. OpenAPI specification is the source of truth for request/response shape.
2. Code implementation must not introduce fields or enum values not present in the spec.
3. Breaking changes require a new version and migration note.

Recommended location for source files:
- contracts/openapi/gateway_api.v1.yaml
- contracts/openapi/gateway_mobile.v1.yaml

---

## Minimum Endpoint Contract Set (Phase 1)

| Endpoint | Method | Auth | Contract Notes |
|----------|--------|------|----------------|
| /api/v1/transactions | POST | Bearer or ApiKey | Idempotency behavior must be explicit |
| /api/v1/transactions/{id} | GET | Bearer or ApiKey | Include trace_id in metadata |
| /api/v1/accounts/{id}/balance | GET | Bearer or ApiKey | Document error model from downstream adapter |
| /health/live | GET | none | Always 200 when process is alive |
| /health/ready | GET | none | 200 only when DB and required adapters are healthy |

---

## Error Contract

All error responses must follow one envelope:

- error.code: machine-readable code
- error.message: user-safe summary
- meta.trace_id: required for support triage

Do not leak downstream raw payloads, SQL errors, or credentials in error messages.

---

## Versioning Rules

1. URL versioning remains supported for compatibility.
2. Accept-header versioning is optional until Phase 5.
3. Any breaking change requires:
- new version
- deprecation notice in changelog
- compatibility test coverage

---

## Contract Validation in CI

1. Validate OpenAPI syntax on every pull request.
2. Run contract tests against controller responses.
3. Block merge when implementation drifts from spec.

---

## Ownership

- Architecture: approves structure and backward compatibility policy.
- API Team: maintains endpoint and schema updates.
- QA: maintains contract regression tests.