CodingArchitectureadvanced

REST & GraphQL API Design & Backwards Compatibility Review

Audit proposed API endpoints for idempotent operations, naming consistency, pagination schemas, and breaking change risks.

#api-design #rest-api #graphql #backward-compatibility #api-review

Compatibility & Specs

Compatible AI Models

ClaudeChatGPTGemini

Last UpdatedOct 3, 2026

Customizable Variables3 parameters

Main Prompt Template3 Variables

164 words • 1244 characters

You are a Principal API Architect and Developer Experience (DX) Specialist. I need a comprehensive design review of a proposed API specification to ensure consistency, security, and zero breaking changes. Proposed API Endpoint Spec or Schema Draft: [api_spec_draft] Target Consumers (Internal Microservices, Mobile Apps, Public Developers): [api_consumers] Performance & Scale Expectations: [scale_expectations] Provide a rigorous API Design Review: 1. RESTful / Schema Hygiene Audit: Inspect resource naming, pluralization, HTTP method usage, header conventions, and status code correctness (e.g. 201 Created vs 200 OK, 422 Unprocessable vs 400 Bad Request). 2. Backwards Compatibility & Versioning Risk: Identify any breaking changes for existing mobile or web clients, and specify how to version or evolve the schema without deprecating endpoints abruptly. 3. Pagination, Filtering & Idempotency Spec: Recommend standardized cursor-based pagination schema (`next_cursor`), multi-field filtering syntax, and `Idempotency-Key` header handling for mutating POST/PUT requests. 4. Standard Error Envelope: Provide a unified RFC 7807 (Problem Details) compliant JSON error schema with machine-readable error codes and localized error messages.

Tip:Variables marked in purple brackets can be tailored below.

Customize Prompt

Fill in the variables below. Your customized prompt updates instantly in the browser — no AI API needed.

Parameters (3)* Indicates required field

Proposed API Spec*[api_spec_draft]

The endpoints, methods, payloads, and parameters proposed

Target Consumers*[api_consumers]

Who consumes this API (React web frontend, iOS/Android apps, third-party partners)

Scale Expectations*[scale_expectations]

Volume and latency requirements

3 parameters active

Live Customized OutputLive Preview

216 words

You are a Principal API Architect and Developer Experience (DX) Specialist. I need a comprehensive design review of a proposed API specification to ensure consistency, security, and zero breaking changes. Proposed API Endpoint Spec or Schema Draft: Proposed REST endpoints: POST /api/v1/createOrganization Payload: { name: string, plan: string, owner_email: string } GET /api/v1/getOrgMembers?orgId=xyz&page=1 Returns: { members: Array<{ id, name, role }> } POST /api/v1/deleteMember Payload: { memberId: string } Target Consumers (Internal Microservices, Mobile Apps, Public Developers): Public B2B API developers and our internal React web dashboard. Performance & Scale Expectations: Organizations with up to 10,000 members; P99 response latency must remain under 120ms. Provide a rigorous API Design Review: 1. RESTful / Schema Hygiene Audit: Inspect resource naming, pluralization, HTTP method usage, header conventions, and status code correctness (e.g. 201 Created vs 200 OK, 422 Unprocessable vs 400 Bad Request). 2. Backwards Compatibility & Versioning Risk: Identify any breaking changes for existing mobile or web clients, and specify how to version or evolve the schema without deprecating endpoints abruptly. 3. Pagination, Filtering & Idempotency Spec: Recommend standardized cursor-based pagination schema (`next_cursor`), multi-field filtering syntax, and `Idempotency-Key` header handling for mutating POST/PUT requests. 4. Standard Error Envelope: Provide a unified RFC 7807 (Problem Details) compliant JSON error schema with machine-readable error codes and localized error messages.

Launch in:

ChatGPT Claude Gemini

How to Use This Prompt

Follow this 3-step workflow to extract high-signal responses from any compatible AI model.

1. Tailor the Parameters

Use the interactive customizer above to substitute the bracketed placeholders with your exact context, requirements, and constraints.

2. Send to AI Model

Copy the prompt and paste it into Claude, ChatGPT, Gemini, or Copilot. These models follow structured multi-step constraints reliably.

3. Review and Iterate

Review the output against the verified benchmark below. Follow up in the conversation to stress-test edge cases or refine tone.

Prompt Variables & Parameters

Reference breakdown of every dynamic variable embedded in this prompt template.

Placeholder	Parameter Name	Type	Status	Description & Guidance
[api_spec_draft]	Proposed API Spec	textarea	Required	The endpoints, methods, payloads, and parameters proposedDefault: Proposed REST endpoints: POST /api/v1/createOrganization Payload: { name: string, plan: string, owner_email: string } GET /api/v1/getOrgMembers?orgId=xyz&page=1 Returns: { members: Array<{ id, name, role }> } POST /api/v1/deleteMember Payload: { memberId: string }
[api_consumers]	Target Consumers	text	Required	Who consumes this API (React web frontend, iOS/Android apps, third-party partners)Default: Public B2B API developers and our internal React web dashboard.
[scale_expectations]	Scale Expectations	text	Required	Volume and latency requirementsDefault: Organizations with up to 10,000 members; P99 response latency must remain under 120ms.

Example Execution & Benchmark Output

Sample input arguments and the verified AI response demonstrating expected quality and formatting.

Sample VariablesInputs

[api_spec_draft]

Proposed REST endpoints: POST /api/v1/createOrganization Payload: { name: string, plan: string, owner_email: string } GET /api/v1/getOrgMembers?orgId=xyz&page=1 Returns: { members: Array<{ id, name, role }> } POST /api/v1/deleteMember Payload: { memberId: string }

[api_consumers]

Public B2B API developers and our internal React web dashboard.

[scale_expectations]

Organizations with up to 10,000 members; P99 response latency must remain under 120ms.

Expected AI ResponseVerified Result

### API Architecture Review Findings #### 1. RESTful Hygiene & Naming Flaws - **Verb-in-URL Anti-Pattern:** `/createOrganization`, `/getOrgMembers`, and `/deleteMember` violate REST conventions by placing verbs in paths. - **Refactored Resource Paths:** - `POST /api/v1/organizations` (creates resource, returns `201 Created` with `Location` header) - `GET /api/v1/organizations/{org_id}/members` (sub-resource collection) - `DELETE /api/v1/organizations/{org_id}/members/{member_id}` (returns `204 No Content`) #### 2. Scalability Bottleneck: Cursor vs Offset Pagination Using `?page=1` will degrade rapidly at 10,000 members because SQL `OFFSET 9000` forces the database to scan and discard 9,000 rows. Replace with opaque cursor pagination: ```json { "data": [...], "pagination": { "has_more": true, "next_cursor": "eyJpZCI6MTIzNCwiY3JlYXRlZF9hdCI6MTY5NjM0fQ==", "limit": 50 } } ``` #### 3. Idempotency Standard for Public API Require `Idempotency-Key: <uuid>` on `POST /organizations` to prevent duplicate charges or duplicate tenant creation during network timeouts.

Best Use Cases

Scenarios and roles where this prompt produces maximum leverage.

Backend engineers designing public developer APIs and partner integrations

Tech leads standardizing API style guides across distributed engineering squads

Mobile developers reviewing backend endpoints for pagination and caching efficiency

Tips for Best Results

Techniques to elevate response fidelity

•Provide rich background context rather than one-sentence inputs to receive deep, non-generic responses.
•Engage in multi-turn conversation: use the initial output as a baseline, then ask the AI to sharpen specific sections.
•Prompt the model to highlight any hidden assumptions or missing trade-offs in its recommendations.

Common Mistakes to Avoid

Frequent failure modes and anti-patterns

•Giving minimal context and expecting nuanced, expert-level strategic output.
•Not validating factual references, citations, or statistical claims with verified primary sources.
•Skipping the customization step and pasting raw bracketed template variables into the AI chat.

Related AI Prompts

Complementary workflows in Coding

View all Coding prompts

Codingadvanced

Production Incident Post-Mortem & Root-Cause Synthesizer

Convert messy incident Slack logs and alerts into a blameless, rigorous post-mortem with corrective action items.

claudechatgptgemini

#post-mortem#root-cause-analysis#sre

View Prompt

Codingadvanced

Monolith to Modular Decoupling & Boundary Architect

Carve clear bounded contexts out of entangled monoliths using the Strangler Fig pattern and event-driven seams.

claudechatgptgemini

#software-architecture#refactoring#monolith-to-microservices

View Prompt

Codingadvanced

Architectural Decision Record (ADR) Analysis & Trade-Off Matrix

Evaluate competing technical architectures, state assumptions, and document a formal Architectural Decision Record.

claudechatgptgemini

#system-architecture#adr#trade-offs

View Prompt

Related Engineering Guides

Deep-dive playbooks and system prompt methodologies for Coding

View all guides

Prompt Engineering#promptarchitecture

8 min read

How to Write Better AI Prompts

A comprehensive playbook for crafting high-fidelity prompts: mastering context, roles, objectives, constraints, output schemas, few-shot examples, and systematic iteration.

Mar 25, 2026Read Guide

Software Engineering#engineering

9 min read

AI Prompts for Software Developers

Turn modern LLMs into senior engineering peers: tactical prompt patterns for architecture review, edge-case test generation, root-cause debugging, and technical documentation.

Mar 27, 2026Read Guide