Direct answer. Design the API around a small, stable resource shape (an enrichment request/result pair), make writes idempotent from day one (idempotent meaning a retried request produces the exact same end result as the original one, so a client's automatic retry after a timeout never re-runs the enrichment or double-counts a record) given the explicit retry-heavy, multi-consumer context, and version the response schema separately from the endpoint path so downstream teams can adopt schema changes on their own timeline rather than a coordinated flag day.
Endpoints and contract.
POST /enrichments accepts a batch of input records (bounded batch size, say up to 500 per call, to keep P95 latency achievable — P95 latency is the response time under which 95% of requests finish; the slowest 5% are allowed to take longer, which is a stricter bar than an average, since an average can look fine even while a meaningful tail of requests runs long) and an Idempotency-Key header; returns 202 Accepted with a Location pointing at a status resource, since enrichment at this volume is realistically an asynchronous operation even if individual small batches complete quickly.GET /enrichments/{batchId} returns the batch's status and, once complete, the enriched results, or partial results with per-item status if some items in the batch succeeded and others failed.- The RESPONSE schema carries an explicit
schema_version field, separate from any URL versioning, so a downstream team's parser can check it and know exactly which fields to expect, without every consumer needing to move in lockstep with every schema change.
Idempotency approach. The Idempotency-Key on the batch submission covers the whole batch as a unit, the same design as a bulk-write endpoint: a retried submission with the same key replays the original batch's result rather than re-running the enrichment (which may call expensive downstream data sources) or double-counting records in whatever aggregate the enrichment service maintains. Given multiple downstream teams calling this service, each team's own key generation needs to be genuinely unique per LOGICAL batch, not accidentally shared across teams; namespacing the key by caller (or requiring the caller's own service identity as part of the key) prevents one team's retries from ever colliding with another's.
Error model. A per-item error structure (not just a single batch-level error) is essential here, since a batch of 500 enrichment requests failing entirely because ONE input record was malformed would be a poor contract for downstream teams; each item's result reports its own success/failure independently, with a batch-level summary count.
Schema versioning as the volume grows. Since "downstream teams" implies multiple independent consumers evolving at different speeds, prefer additive-only changes to the response schema (new optional fields) over breaking ones whenever possible, and reserve an actual version bump for the rare case an existing field's meaning or type must change; this keeps most schema evolution invisible to consumers who do not care about the new field, rather than forcing every consumer to move in lockstep.
Validating the design can sustain 1,000 requests per second at P95 200ms. At a high level: load-test the actual enrichment path (not just the API's own request handling) against realistic downstream-dependency latency, since the enrichment logic calling external or internal data sources is very likely the true bottleneck, not the HTTP layer itself; confirm the idempotency-key storage lookup (a single indexed read per batch) stays cheap under this load, since that lookup sits on every request's critical path; and measure P95, not average latency, specifically, since an average can look fine while a meaningful tail of requests blows past the 200ms target.
Trade-offs and pitfalls. The most common mistake at this specific intersection (idempotency plus versioning plus multiple independent consumers) is designing the idempotency key and the schema-versioning strategy in isolation from each other; a schema change that alters what a stored (already-completed) idempotency result even MEANS can make an old cached response invalid for a client expecting the new schema, which needs an explicit policy (does an idempotency-key replay always return the schema version it was originally created under, or the current one?) rather than being left to accident.
