API Design Doctor — Review APIs Before Release

Pre-Release API Review — Hypothetical Excerpt

Scope: Only the three example operations supplied in the prompt were reviewed. They are hypothetical and no code, OpenAPI document, consumers, or live service was inspected. Severity below is a design risk assessment, not a confirmed exploit.

Findings

HIGH — Retry can create duplicate orders. POST has no documented idempotency key or replay semantics. A timeout leaves the caller uncertain whether the first request succeeded. Define an Idempotency-Key scoped to authenticated tenant and operation; persist request hash and final response; same key/same payload replays the original result, while same key/different payload returns a documented conflict. Set key retention to cover the supported retry window.
2. HIGH — Tenant ownership is client supplied and authorization is unspecified. A body tenant_id must never be trusted as proof of access. Derive tenant context from authenticated identity, authorize customer and every order resource server-side, and prevent cross-tenant reads/writes. Avoid exposing whether another tenant's order exists.
3.

MEDIUM — Unbounded list and unstable ordering. Define cursor pagination with a stable unique tie-breaker, deterministic default sort, bounded page size, and documented next-cursor behavior. Apply tenant authorization before filtering/pagination; do not use pagination as an authorization boundary.
4. MEDIUM — PATCH has unclear mutation and validation semantics. Specify allowed fields, media type and patch semantics, required fields, null versus omitted behavior, immutable fields, validation errors, and concurrency control. Reject unsupported fields rather than silently pretending changes succeeded.
5. MEDIUM — Inconsistent errors impair clients and may leak internals. Adopt one versioned error envelope with stable machine code, safe message, request/correlation ID, and structured field violations. Never return raw framework traces or secrets. Document status mappings and retryability.
6.

LOW/MEDIUM — POST success semantics ambiguous. If creation is synchronous, return 201 Created, a Location header, and the resource representation. If processing is asynchronous, return 202 Accepted with an operation resource and polling/webhook contract. Choose based on actual workflow and document it.

Safer contract sketch

Create: POST /v1/orders with customer_id and validated items; tenant comes from authenticated principal, not the payload. Require Idempotency-Key. Return 201 + Location + order_id/status/resource on first success; exact replay returns the same recorded outcome. Return 409 for an idempotency-key payload mismatch.

Read/list: GET /v1/orders?limit=50&cursor=... with a bounded limit, deterministic order, opaque cursor, and next_cursor. GET /v1/orders/{order_id} checks tenant ownership before returning data.

Update: define an explicit patch format and allowlist of mutable fields. Require If-Match/ETag or a version field for concurrent updates; return 412 on stale precondition. Return 400/422 with the standard error schema for malformed or semantically invalid requests.

Release gates

• Contract tests for create, exact replay, key/payload mismatch, timeout-after-commit retry, and asynchronous behavior if applicable.
• Authorization tests for cross-tenant create, list, get, patch, guessed IDs, and pagination cursors.
• Schema validation tests for missing, null, empty, unknown, and boundary-valued fields.
• Pagination tests for stable ordering under inserts and no skipped/duplicated records across cursors.
• Concurrency tests for stale ETag; error-envelope and no-sensitive-data assertions.
• Compatibility check against existing SDKs/consumers, documented deprecation and migration plan, rate limits, observability, and rollback.

Open questions: Is creation synchronous? What identity and tenant model exists? Which fields can change? Are orders immutable after payment? What are retention, privacy, and availability requirements? These affect the final contract; no implementation or security test is asserted here.