API Contract Design for Legal System Integration

Design an API contract. Assumption: the other side will not be able to change their implementation after the contract is agreed.

Integration purpose: [describe] Consumer: [internal system / client / vendor] Constraints: [authentication, network, regulatory]

Produce a partial OpenAPI spec covering:

1. Endpoints — path, verb, and purpose. Plural resources; actions expressed through the verb, not the path.
2. Request and response schemas — every field with type, required or optional, and an example. Leave no field undescribed.
3. Errors — for each endpoint, every possible error code with a structured body: a stable error code, a human message, and a field pointing at what to fix. Never a bare free-text string.
4. Idempotency — for every write operation, how duplication is prevented on retry. Idempotency key, validity window, and repeat-call behaviour.
5. Pagination and filtering — cursor, not offset. Explain why offset breaks under concurrent writes.
6. Versioning — how a field is added without breaking consumers, and what counts as a breaking change. Define the deprecation policy.
7. Authentication and authorisation — mechanism, token lifetime, and how access is revoked immediately.
8. Limits — rate limit, max body size, timeout, and behaviour on exceeding them.

Finally: three plausible future changes, and how the contract accommodates each without breaking.