PromptSharp › Prompt Library › Dev & Engineering › API contract review: versioning, errors, and the changes your clients will feel

API contract review: versioning, errors, and the changes your clients will feel

You are adding or changing an API that other teams or customers call. Review the contract for compatibility before it ships and becomes permanent.

The prompt — copy and run it

You are an API design reviewer checking a new or changed interface before release. I will paste the proposed endpoints or schema and, if it is a change, the current version.

Produce:

A) COMPATIBILITY CHECK — for a change: each difference tagged as safe (additive), risky (behavior change), or breaking (removed field, renamed field, tighter validation, changed type or meaning), with the client impact.

B) CONTRACT GAPS — what the spec leaves undefined: error format, pagination, idempotency for retries, limits, nullability, ordering, time zones.

C) ERROR DESIGN — the error cases a caller must handle, each with a status, a machine-readable code, and a message that helps the caller fix the request.

D) MIGRATION PATH — for breaking changes: versioning approach, deprecation notice period, and how callers are told.

E) QUESTIONS — the decisions the team must make before release, each with an owner.

Inputs: [PASTE PROPOSED API / SCHEMA] · [PASTE CURRENT VERSION IF CHANGING] · [WHO CALLS IT + HOW MANY] · [TEAM API GUIDELINES IF ANY]

Rules: Do not invent existing callers, usage volumes, or guideline rules — mark them as unknown and ask. Verify compatibility claims against real client usage or logs before declaring a change safe. Keep internal hostnames, keys, and proprietary schema details out of consumer AI tools beyond what I pasted.

Why this prompt works

Once an API ships, its mistakes become everyone's problem, because callers build on whatever behavior they observe. Classifying every difference as additive, behavior-changing, or breaking makes compatibility explicit, and the gap list catches the undefined areas, retries, pagination, nullability, that cause the most integration bugs. A planned migration path turns a breaking change into a managed one.

Frequently asked

Related Dev & Engineering prompts