REST API Design Review and Breaking-Change Check
Review REST endpoints or OpenAPI diffs for breaking changes, naming, errors, pagination, and idempotency, with ranked fixes.
Before & after
Same prompt, same agent — the only difference is the skill.
API design is important for making your API usable and predictable. You'd want consistent naming conventions across endpoints and consistent response formats. Versioning strategies help with managing changes over time. Documentation is critical so users understand how to use your API. You might also think about security, rate limiting, and error handling. Breaking changes can cause problems for existing users, so it's good to be careful about that. There are various guidelines and best practices for API design that you could reference.
API DESIGN REVIEW SCORECARD FOR V2 LAUNCH:
CONSISTENCY AUDIT
Naming conventions:
✓ Nouns for resources: GET /v2/accounts, POST /v2/invoices
✓ Verbs as subresources: POST /v2/accounts/123/invite
✓ Snake_case for fields: created_at, account_id, not createdAt
Response format:
✓ Success: { status: 'success', data: {...} }
✓ Error: { status: 'error', code: 'VALIDATION_FAILED', message: '...' }
✓ All endpoints return consistent wrapper (no inconsistent raw arrays)
BREAKING CHANGES DETECTED
1. BLOCKER: GET /v1/reports → removed, no deprecation period
→ Add v1 endpoint with 301 redirect to v2
2. WARNING: POST /v2/accounts now requires 'billing_email' (was optional)
→ Add default behavior or deprecation warning header
3. MINOR: Response field 'user_count' renamed to 'active_users'
→ Include both fields in transition period
DESIGN SMELLS FOUND
• Endpoint GET /v2/accounts/search missing pagination (could return 100K+ results)
→ Add limit/offset parameters
• PATCH /v2/invoices accepts full invoice object, but only updates 3 fields
→ Clarify docs which fields are patchable
DESIGN SCORECARD
Endpoint consistency: 9/10 (naming and structure clear)
Documentation completeness: 7/10 (missing error code glossary)
Versioning strategy: 8/10 (no sunset date for v1)
Security: 8/10 (missing rate-limit headers in response)
RECOMMENDATION: Ship v2 after fixing breaking-change warnings
About this skill
Your PR adds one innocent-looking field and the Android app starts crashing. Your pagination skips rows. Your PATCH endpoint quietly drops typos, so the setting never saves. This skill reviews your endpoints, OpenAPI spec, or API diff with the question that matters after launch: what breaks for clients you can't force to upgrade?
What it does
- Classifies every change by direction (request vs response). It catches the breaks schema diffs miss: new required params, response enum additions, changed defaults, and changed status codes.
- Flags the decisions that become permanent after the first client ships: ID types, money and timestamp formats, top-level arrays, error shape, and pagination model.
- Checks method semantics: PUT vs PATCH (merge patch vs JSON patch), 201/202 usage, idempotency keys for retried POSTs, and ETag/If-Match for lost updates.
- Catches design-level security holes: object-level authorization on path IDs, mass assignment, over-exposed fields, and unbounded page sizes.
- Standardizes errors on RFC 9457 problem details with stable machine-readable codes.
- Plans evolution: which fixes ship additively now, and which get batched into one versioned release with deprecation headers.
What you get
A verdict (Ship / Ship with fixes / Block) and severity-ranked findings. Each finding names the client that breaks and gives the exact replacement schema, header, or status code. Full audits also include a scorecard and a migration order.
Best for
Backend engineers and tech leads reviewing endpoint PRs, teams auditing a public or partner API before a v2, and anyone writing API standards their linter and reviewers can actually enforce.
SKILL.md preview
---
name: rest-api-design-review
description: Reviews REST endpoints, OpenAPI specs, or API diffs. It classifies each change by direction (request vs response) to find breaking changes, then checks the decisions that become permanent, method and status semantics, error and pagination shape, concurrency, and design-level security. It returns severity-ranked fixes and a ship/block verdict. Use when the user says "review this API", "is this a breaking change?", "check my OpenAPI diff", "audit our API before v2", "write API design standards for our team", "our mobile app broke after we changed the endpoint", or "my pagination keeps skipping items".
---
… (sign up to view the full skill)More development skills
View all Development skills →Production Go: Concurrency, Services & Profiling
Production Go code with leak-free goroutines, context-correct services, wrapped errors, and pprof-driven performance fixes.
Backend Feature Build Plan
Builds one backend feature through gates: confirmed requirements, one-screen design, small tested slices, and a deploy/rollback handoff.
Consistent, Safe Application Logging
Adds structured, correlated logs with useful severity, safe fields, bounded volume, and targeted verification.
Reliable WebSocket Messaging and Scaling
Build WebSocket and Socket.IO systems with authorized rooms, reconnect recovery, bounded queues, and multi-node presence.