A bad API contract is a three-year migration debt that you pay one customer support ticket at a time — every renamed field, silently widened 200, and inconsistent pagination style multiplies across every downstream SDK. These prompts make AI walk the contract like an outside consumer would: hunting status-code lies, generic 500s with no machine code, breaking changes hidden in “minor” releases, and the gaps between 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.
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. Propose improvements.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).
{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-query allowlists or query-cost limits to avoid abusive queries; 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.
Common mistakes
- Inconsistent naming across endpoints
- Generic 500 errors with no error code
- Breaking changes without deprecation window
- Different pagination per endpoint
- No idempotency keys on writes
- Spec and reality drifting over time
Related
- Database schema review prompts
- Code review prompts
- Security audit prompts
- Performance optimization prompts
- Deployment check prompts
Tags: #Prompt #AI coding #AI coding