Rpc And Api Contracts

---
name: rpc-and-api-contracts
description: >
  The contract between two services and how it changes without a coordinated deploy: partial
  failure as a first-class outcome, an error surface a machine caller can act on (stable
  extensible codes, outcome certainty, retry conditions, RFC 9457), compatibility in both directions and
  expand-then-contract, versioning under an explicit compatibility policy, and choosing REST,
  gRPC or messaging on observable conditions. Use when a client branches on an error message
  string, when a field is renamed or a
  proto field number reused, when a rolling deploy breaks consumers, when a synchronous
  endpoint fronts a long-running operation, when a new version is proposed for an additive
  change, or when a consumer fails on an unknown JSON property. Does not cover delivery
  guarantees (delivery-semantics), the deadline itself (timeouts-and-deadlines), wire-format
  cost (serialization-performance), the exception hierarchy (java-exception-design), or event
  contracts (event-driven-architecture).
---

# RPC And API Contracts

## Purpose

A contract binds for as long as the oldest caller and the oldest stored message live, not for
as long as a deploy takes. The failure this prevents is the change that is correct in the
repository and an outage in the fleet: a renamed field, a narrowed type or a reused field
number shipped as one deploy into a rolling upgrade where both versions are running at once.

The second failure is an error surface designed for a human reading a log. A machine caller
has to decide retry or not, fall back or not, page or not. If that decision requires parsing
English, the client is coupled to your wording and every rephrasing is a breaking change.

## Compatibility and evidence

Inspect supported clients, deployed Java/framework/serializer versions, generated artifacts,
actual mapper configuration and rollout/retention policy. The record sketch requires Java
16+; Spring `ProblemDetail` requires Spring Framework 6+ (Java 17+). Do not upgrade a target
or regenerate every client merely to fit an example. Unknown client inventory or absent
telemetry leaves compatibility unverified; propose how to close the gap without inventing
proof of either compatibility or incompatibility.

## Workflow

Use the steps relevant to the requested contract decision. Reuse adequate artifacts, cohort
evidence and tests; a narrow explanation or supported no-change review does not require a
new error schema, rollout campaign or version. State the missing evidence only for claims
that depend on it.

1. **Decide what the call actually is** before choosing a transport: a synchronous answer, or
   an acceptance of work. Long-running synchronous work needs queryable operation identity
   or reconciliation for ambiguous timeout; asynchronous acceptance must define status,
   retention and eventual failure too.
2. **Design the error surface around caller decisions.** Give stable problem types/codes,
   outcome certainty (rejected versus may-have-applied), retry precondition/advice, field
   violations and a status/operation URI where applicable. Retry safety composes method
   semantics, idempotency key, current state and failure—not one universal boolean.
3. **Classify every change** as additive, compatible-in-one-direction, or breaking, and name
   which side may deploy first. See `references/contract-evolution.md`.
4. **Plan a verified transition for a breaking change.** Expand → migrate → contract is a
   common bridge; an adapter, versioned coexistence or a controlled replacement may fit the
   supported-client policy. A rename needs covered rollout/replay pairs, not automatic dual-writing.
5. **Prove the coexistence pairs the rollout can create.** Test old-reader/new-writer and
   new-reader/old-writer where deployment order or durable data permits each. Include retries,
   cached/stored payloads, rollback and unknown error/enum values.
6. **Apply the published version policy.** A compatible schema/release identifier need not
   create a breaking endpoint version. When retirement is in scope, use bounded version/client
   telemetry or protected logs together with supported inventory and the retirement contract.

## Rules

- Partial failure is the difference that matters: after dispatch, a timeout/disconnect may mean
  the callee applied the effect. The contract must provide a stable operation/idempotency key,
  status lookup/reconciliation, or explicitly expose the unresolved outcome (`idempotency`).
- Transport exceptions alone often cannot distinguish lost request from lost response.
  Protocol/application evidence can: pre-dispatch failure, durable operation status or a
  deduplicated retry. Do not infer peer state from timeout class.
- Error codes are a documented **extensible** set unless the API version promises otherwise.
  Known meanings remain stable; clients need a conservative unknown-code path. Human-readable
  text is explicitly **not** the machine branching contract. Distinguish occurrence-specific
  detail from RFC 9457's normally stable title; document localization/redaction and any
  existing presentation guarantees rather than assuming every textual change is harmless.
- The response can carry `outcome=REJECTED|UNKNOWN`, `retryCondition`, `Retry-After` or an
  operation-status URI. The client combines those with idempotency and deadline. A naked
  `retryable=true` cannot express "refresh state", "same key only" or ambiguity.
- RFC 9457 (which obsoletes RFC 7807) defines `application/problem+json` with `type`,
  `title`, `status`, `detail` and `instance`. Put application-specific machine members — code,
  outcome/retry condition and correlation id — in extension members, never inside `detail`.
  The standard `type` URI is already the primary problem identifier; `code` is optional.
- In gRPC, mapping every failure to `INTERNAL` loses semantics, but no status is universally
  retryable. `UNAVAILABLE` may still be ambiguous for a mutation; `RESOURCE_EXHAUSTED` may be
  quota or capacity; `ABORTED` commonly means retry a higher transaction; `DEADLINE_EXCEEDED`
  can occur after effect. Publish method-specific retry policy and structured details.
- Compatibility has a direction, and terminology varies by ecosystem. Define it explicitly:
  backward (new reader reads old data) usually permits consumers first; forward (old reader
  reads new data) permits producers first. Full compatibility covers the evaluated version pairs;
  adjacent checks alone do not establish historical/transitive compatibility. Arbitrary
  coexistence requires every relevant supported pair to pass;
  an ordered rollout can rely on one direction only if rollback and all live/stored pairs are
  controlled.
- The compatibility horizon is the maximum of live old-client lifetime, rollback window,
  broker/cache retention, DLQ/operator replay, backup restore and archived reprocessing.
  Required direction can change across rollout phases; it is not always both for retention.
- Apply format-specific identity rules: never reuse Protobuf field numbers (reserve removed
  numbers/names); JSON/Avro names and aliases differ. Type, validation or domain narrowing is
  breaking for values old clients may send/read. Introduce required fields through an
  optional/defaulted and negotiated transition.
- Proto3 implicit-presence singular scalars conflate absent/default; `optional`, message fields
  and Editions explicit presence preserve it. Check protoc/runtime/API compatibility before
  introducing presence into generated clients.
- Plain Jackson 2.18.3 enables `FAIL_ON_UNKNOWN_PROPERTIES` by default; Boot 3.5.0's
  auto-configured Jackson 2 mapper disables it. Jackson 3.0.0 defaults it to false. Custom mappers, annotations
  and readers can differ; verify the actual client. Unknown properties and unknown enum
  values are separate policies.
- Retirement needs evidence appropriate to the supported population, including dormant
  clients and replay. Zero requests during a short window is not proof of no dependency.
- Choose the transport on conditions, without treating style as destiny: **gRPC** often fits
  controlled service clients when deadline/cancellation propagation, generated schemas or
  streaming matter; browser/public use requires compatible gateway/tooling. **REST/JSON**
  when the caller set is open or browser-based, intermediary caching matters, or clients
  cannot be made to regenerate stubs. REST can stream and gRPC can serve public clients at
  additional ecosystem cost. **Messaging** when the producer must not wait, when
  fan-out or replay is required, or when consumer availability must not bound the producer —
  at which point the delivery guarantee becomes part of the contract (delivery-semantics).

- Propagated deadlines/cancellation do not prove server work or downstream effects stopped.
  Define cooperative cleanup and preserve ambiguous outcomes after dispatch.
- `If-Match` uses strong comparison; enforce the precondition atomically with the mutation.
  Idempotency keys need authenticated scope, operation, request fingerprint and retention;
  coordinate deduplication with effects and define concurrent/unknown completion behavior.

## Contract dimensions often omitted

- authentication/authorization scope, tenant isolation and whether existence errors leak data;
- idempotency namespace/retention and operation-status lifecycle for `202 Accepted`;
- pagination cursor opacity/stability, filtering/sort semantics and snapshot consistency;
- numeric units/ranges, Unicode, time zone/precision and absent/null/empty distinctions;
- payload/metadata limits, compression, cancellation and deadline propagation;
- cache validators/conditional requests, privacy/redaction and audit requirements;
- rate-limit, deprecation/sunset signals and capability negotiation.

For affected contracts, validate the relevant invariants, failure semantics and actual rollout
pairs; a schema label alone does not establish them. Return the supported decision or change,
its evidence and unresolved limits. Include deployment order, outcome/retry policy or further
checks when the decision depends on them. Retain an adequate contract and do not equate an
untested required pair with a pass.

## References

- [Contract and schema evolution](references/contract-evolution.md) — the compatibility
  matrix with who deploys first, the expand/migrate/contract sequence, the concrete rules for
  JSON, Protobuf and Avro, the versioning decision block, and exactly what a consumer-driven
  contract test proves and does not. Read before changing any shared message, endpoint or
  schema, and before proposing a new version.
- [The error contract in Java](references/error-contract.md) — a problem-details record with
  its contract and non-contract members separated, the single place a status becomes a
  decision, the gRPC status mapping table, and how a client acts without matching a string.
  Read when designing or reviewing the error surface of an API or client.