A bad API contract is a three-year migration debt you pay one support ticket at a time. Every renamed field, every silently-widened 200 response, every inconsistent pagination style multiplies across every downstream SDK and every customer integration. These 15 prompts make an AI model walk your contract the way an outside consumer would: hunting status-code lies, generic 500s with no machine code, breaking changes hidden in “minor” releases, and the gaps between your OpenAPI spec and what the server actually returns. For deeper schema-level pressure on the storage layer behind these endpoints, pair with the database schema review prompts.
TL;DR
- Paste these prompts into a long-context model and feed it the spec plus 5-10 real request/response pairs. As of June 2026, the strongest picks are Claude Opus 4.7 (1M-token context, top SWE-bench Verified at 87.6%) and Gemini 3.1 Pro (also 1M, cheapest at $2/$12 per 1M tokens). Both swallow a full OpenAPI or GraphQL SDL in one pass.
- An AI review is a fast first pass, not a gate. Pair it with deterministic tooling:
oasdifffor REST breaking-change detection (450+ rules, OpenAPI 3.0 and 3.1, GitHub Action) andgraphql-inspectorfor GraphQL schema diffs that label each change breaking / dangerous / safe. - Standardize your error body on RFC 9457 Problem Details (
application/problem+json). Prompts 2 and 3 below check exactly for this. - REST and GraphQL need different stress. Status codes and cacheability bite REST; N+1 fan-out, field-level auth, and query-cost limits bite GraphQL. The split table at the end shows what to emphasize.
Best for
- REST API design reviews
- GraphQL schema reviews
- Public SDK pre-launch
- B2B integration contracts
- Backwards-compat audits
1. Endpoint-naming consistency
Applies to: REST
Below is a list of REST endpoints. Evaluate naming consistency: (a) noun vs verb, (b) plural vs singular, (c) nesting depth, (d) versioning style. Flag inconsistencies and propose a normalized naming scheme.
{paste endpoints}2. Error-model audit
Applies to: REST + GraphQL
Below is the API's error model: {paste examples}. Evaluate: (a) is the error code stable, (b) does it carry a human message AND a machine code, (c) does it expose internal details, (d) does it support retry hints, (e) how far is it from RFC 9457 Problem Details (type/title/status/detail/instance, application/problem+json). Propose improvements and an RFC 9457-aligned shape.3. Status-code semantics
Applies to: REST
Below are 10 endpoints with their returned status codes. For each, verify: (a) is the code semantically correct (e.g., 404 vs 410 vs 422), (b) is the code consistent across endpoints, (c) are clients likely to misinterpret. Flag and propose fixes.
{paste}4. Versioning strategy review
Applies to: REST + GraphQL
My API versioning: {paste current strategy — URL / header / query / none}. Evaluate against my consumer profile: {paste}. Output: pros / cons of current vs alternatives, and which to adopt going forward.5. Backwards-compat diff
Applies to: REST + GraphQL
Below: the current API spec and the proposed new version. Find all breaking changes (field removed, type changed, required field added, error shape changed). For each: severity, who breaks, mitigation (deprecation period / dual-write / version). Cross-check your list against what an automated diff (oasdiff for OpenAPI, graphql-inspector for GraphQL) would flag, and call out anything those tools miss because it is semantic rather than structural (e.g., a field that still exists but changed meaning).
{paste}6. Pagination consistency
Applies to: REST
Below are list endpoints with their pagination styles ({paste}). Evaluate: (a) cursor vs offset vs page-token consistency, (b) total-count semantics, (c) does pagination work for high-cardinality lists. Propose a unified pattern.7. GraphQL schema smell finder
Applies to: GraphQL
Below is a GraphQL schema. List the top 5 smells: (a) overly nullable fields, (b) circular types, (c) missing input types, (d) misuse of Connection, (e) over-fetching risk. Each with a 1-line fix.
{paste schema}8. Request / response contract gaps
Applies to: REST + GraphQL
Below: API spec + 5 example requests + 5 example responses. Find gaps where spec and reality diverge — fields in response not in spec, fields in spec never returned, optional vs required mismatches.
{paste}9. Idempotency-key audit
Applies to: REST
Below are POST endpoints that should support retries. For each: (a) is there an idempotency key, (b) what is the dedup window, (c) what happens if the same key is reused with different bodies, (d) how is duplicate detection surfaced to clients.10. Rate-limit & quota documentation
Applies to: REST + GraphQL
Below: current rate-limit behavior. Evaluate: (a) is the limit per IP / per key / per resource, (b) is there a Retry-After header, (c) is there a 429 body schema, (d) does the doc match reality. Propose docs + behavior fixes.
{paste}11. SDK ergonomics review
Applies to: REST
I am pre-generating an SDK from this OpenAPI spec. Below: 5 representative endpoints. Evaluate how they'll feel in {TypeScript / Python / Go}: are types clean, are method names sensible, are required vs optional clear. Suggest spec changes to improve SDK feel.
{paste}12. Webhook contract review
Applies to: REST + GraphQL
Below is my webhook payload + headers. Evaluate: (a) signature scheme, (b) replay protection, (c) event ID + version, (d) ordering semantics, (e) retry behavior. Propose changes to make consumers' lives easier.
{paste}13. Connection-style pagination review
Applies to: GraphQL
Below are Relay-style Connection fields in my GraphQL schema. Review: (a) does each Connection expose edges, nodes, and pageInfo, (b) does pageInfo include hasNextPage AND endCursor (and hasPreviousPage / startCursor where backward paging is supported), (c) is the cursor opaque and stable across re-queries, (d) are the Connection conventions consistent across all paginated fields (same arg names: first / after / last / before), (e) any field returning a raw list that should be a Connection. Flag inconsistencies and propose fixes.
{paste schema}14. N+1 detection in resolver design
Applies to: GraphQL
Below are resolver definitions for {paste type}. Walk through them field-by-field. For each field, ask: (a) does it trigger a per-parent fetch, (b) where should a DataLoader / batch loader be inserted, (c) does the field look harmless but fan out under nested queries (e.g., list of authors -> books -> reviews). List every N+1 risk and the DataLoader key shape that would fix it.
{paste resolvers}15. Resolver field-level authorization
Applies to: GraphQL
Below is a GraphQL schema with annotated auth rules. Review: (a) are auth checks per-field or only per-query, (b) which type-level rules are correct vs which fields need finer-grained rules, (c) which fields leak data via partial-success responses, (d) are the rules compatible with persisted queries (no runtime arg-dependent checks that change behavior unpredictably), (e) any field where auth depends on parent context but resolver doesn't have it. Propose a per-field auth matrix.
{paste schema + auth}REST vs GraphQL review focus differs
REST and GraphQL share some checks (versioning, error model, contract drift) but the things that bite you in production differ. Adjust what you stress in review:
- Status codes / cacheability: REST review cares deeply about 4xx vs 5xx semantics, Cache-Control headers, and CDN behavior. GraphQL almost always returns 200 with errors in the body, so this category mostly does not apply.
- N+1 and resolver cost: GraphQL-only concern. REST endpoints are eager by design. In GraphQL, a nested query can fan out unbounded if DataLoader is missing.
- Field-level authorization: REST authorizes the endpoint; GraphQL must authorize each field. A field that looks safe on its own can leak data when reached via a nested path.
- Persisted queries and cost limits: GraphQL-only. Public GraphQL needs persisted queries (a.k.a. trusted documents: an allowlist of pre-registered operations clients reference by ID) or query-cost limits to avoid abusive nested queries. This is the recommended production pattern across Apollo GraphOS and the GraphQL Foundation. REST has rate limits per endpoint instead.
- Pagination shape: REST tolerates several styles (offset, cursor, page token) as long as each endpoint is consistent. GraphQL is expected to follow the Relay Connection spec across the entire schema.
What AI catches vs what it misses
These prompts are a force multiplier on a senior reviewer, not a replacement for one. From running them on real specs, the split is consistent:
| AI is reliably good at | AI is unreliable at |
|---|---|
| Naming inconsistencies across many endpoints | Whether a 422 vs 409 choice matches your domain |
| Spotting generic 500s and missing machine codes | Knowing your actual consumers and their tolerance |
| Listing structural breaking changes from a diff | Business-meaning changes a field’s semantics |
| Flagging missing DataLoader / N+1 candidates | Real query patterns and their cost in production |
| Drafting an RFC 9457-aligned error shape | Whether a field’s data is legally sensitive |
Run the AI pass first to triage, then put the high-severity findings in front of a human and validate breaking changes with oasdiff or graphql-inspector in CI so nothing structural slips through silently.
FAQ
Which model should I paste these into? As of June 2026, use a 1M-token model so the whole spec plus examples fit in one pass: Claude Opus 4.7 (top SWE-bench Verified, 87.6%) or Gemini 3.1 Pro (cheapest at $2/$12 per 1M tokens). On ChatGPT Plus, the in-app context is roughly 320 pages; for a large OpenAPI spec you may need the $200 Pro tier or the API to get the full window.
Do these replace oasdiff and graphql-inspector?
No. Those are deterministic and belong in CI as a hard gate; oasdiff covers 450+ breaking-change categories for OpenAPI 3.0 and 3.1, and graphql-inspector labels every schema change breaking / dangerous / safe. The prompts add semantic judgment the tools cannot make, such as a field that still exists but changed meaning.
What error format should the prompts target?
RFC 9457 Problem Details (media type application/problem+json), which obsoleted RFC 7807 in July 2023. It standardizes type, title, status, detail, and instance, plus an extension for a stable machine code. Prompts 2 and 3 check for it.
Why do REST and GraphQL need different prompts? Different failure modes. REST review centers on status-code semantics and cacheability; GraphQL review centers on N+1 resolver fan-out, per-field authorization, and query-cost limits. The split table above shows where to focus each one.
How many examples should I paste? Five to ten real request/response pairs alongside the spec. Contract drift (prompt 8) only surfaces when the model can compare what the spec claims against what the server actually returns, so synthetic examples hide the exact bugs you are hunting.
Related
- Database schema review prompts
- Code review prompts
- Security audit prompts
- Performance optimization prompts
- Deployment check prompts
Tags: #Prompt #AI coding #AI coding