Engineering Advanced APIReviewREST

API Design Reviewer

REST API linter, breaking change detector, and design scorecard.

$skillfish add ~skills/api-design-reviewer

Real Examples Get Started Models & Context

Real Conversations

See how the API Design Reviewer skill responds to actual requests. These are representative examples of what your AI agent will produce.

You

We're launching our public API next month. We have things like POST /api/getUsers, response fields mixing snake_case and camelCase, and no versioning. Score us and tell me what to fix first.

Agent

Running the API scorecard. Here's the assessment:

Overall Grade: C (61/100)

Dimension	Score	Weight	Key Issue
Consistency	14/30	30%	Mixed casing throughout
Documentation	14/20	20%	Missing request/response examples
Security	10/20	20%	No rate limit headers documented
Usability	8/15	15%	Verb-based URLs
Performance	0/15	15%	No pagination, no cache headers

Critical fixes before launch:

POST /api/getUsers → GET /api/v1/users GET is safe and idempotent — clients can cache, retry, and bookmark it. Verbs in URLs violate REST; the HTTP method is the verb.

Pick one casing, enforce everywhere:

// Bad — mixed in same response
{"user_id": 123, "firstName": "Jane", "last_name": "Doe"}
// Good — camelCase throughout
{"userId": 123, "firstName": "Jane", "lastName": "Doe"}

Add URL versioning now — /api/v1/users — much harder to retrofit after launch

Paginate every list endpoint:

{"data": [...], "pagination": {"nextCursor": "abc", "hasMore": true}}

Fix these 4 and you hit B+ (83/100). Want me to run breaking_change_detector.py once you've drafted the revised spec?

You

We're upgrading from v1 to v2. In v2 we renamed user_id to id, removed GET /api/v1/users/:id/profile, and made email required on POST /users. What breaks for existing clients?

Agent

Running breaking change detection. Three breaking changes, severity-ranked:

BREAKING — HIGH

1. Endpoint removed: GET /api/v1/users/:id/profile Any client calling this gets 404. Migration: embed profile as an optional object on GET /api/v2/users/:id?include=profile, or maintain a v1 compatibility shim with a Sunset header:

Deprecation: true
Sunset: Sat, 01 Nov 2026 00:00:00 GMT

2. Field renamed: user_id → id in all user responses Clients reading response.user_id get undefined. Affects GET /users, GET /users/:id, POST /users. Transition strategy:

{"id": 123, "user_id": 123}  // return both during transition; remove user_id in v3

3. New required field: email on POST /api/v2/users Clients sending POST without email now get 422. Return a clear error:

{"error": {"code": "MISSING_REQUIRED_FIELD", "field": "email", "message": "email is required as of v2"}}

Recommended migration path: Ship v2 alongside v1. Set v1 deprecation date 6 months out. Publish a migration guide at /docs/migrate-v1-to-v2. Monitor which clients are still hitting v1 endpoints via API gateway logs before sunset.

You

Our mobile team says the REST API over-fetches — they need 3 fields from /users but get 40. Our web team loves the current REST setup. Should we add GraphQL?

Agent

Don't add GraphQL yet. Fix REST with field selection — 1 day vs 2 weeks.

Option A: Sparse fieldsets (recommended)

GET /api/v1/users/123?fields=id,name,avatarUrl

{"id": 123, "name": "Jane Doe", "avatarUrl": "https://cdn.example.com/..."}

Implementation (FastAPI):

@app.get("/api/v1/users/{id}")
def get_user(id: int, fields: str = None):
    user = db.get_user(id)
    if fields:
        allowed = set(fields.split(",")) & ALLOWED_FIELDS
        return {k: v for k, v in user.dict().items() if k in allowed}
    return user

Web team: unchanged — no ?fields param returns all 40 fields
Mobile team: ?fields=id,name,avatarUrl returns 3 fields only
No new auth surface, no query complexity problem, no DataLoader setup

When GraphQL makes sense: 3+ distinct client types with fundamentally different data shapes, or you need real-time subscriptions. At your scale (2 clients), the overhead isn't worth it.

Also add: Cache-Control: private, max-age=60 on /users/:id — mobile clients will cache automatically and cut API calls ~30%.

Scorecard improvement: Performance 0/15 → 10/15 with field selection + cache headers.

Get Started

How to install and use this skill in your preferred environment.

Skills are designed for AI coding agents (Claude Code, Cursor, Windsurf) and IDE-based workflows where the agent can read files, run scripts, and act on your codebase. Web-based AI can use the knowledge and frameworks, but won't have tool access.

Models & Context

Which AI models and context windows work best with this skill.

Recommended Models

Best

Claude Opus 4 Claude Sonnet 4 GPT-4.1 Gemini 2.5 Pro Grok 3 Kimi K2

Good

Claude Haiku 4.5 GPT-4.1 mini Gemini 2.5 Flash Grok 3 mini

Larger models produce more detailed, production-ready outputs.

Context Window

This skill's SKILL.md is typically 3–10 KB — fits in any modern context window.

8K Skill only

32K+ Skill + conversation

100K+ Skill + references + codebase

All current frontier models (Claude, GPT, Gemini) support 100K+ context. Use the full window for complex multi-service work.

Pro tips for best results

1

Be specific

Include numbers — users, budget, RPS — so the skill can size the architecture.

2

Share constraints

Compliance needs, team size, and existing stack all improve the output.

3

Iterate

Start with a high-level design, then ask follow-ups for IaC, cost analysis, or security review.

4

Combine skills

Pair with companion skills below for end-to-end coverage.

Ready to try API Design Reviewer?

Install the skill and start getting expert-level guidance in your workflow — any agent, any IDE.

$skillfish add ~skills/api-design-reviewer

← Browse all 169 skills

API Design Reviewer

Real Conversations

Get Started

Claude Code, OpenCode, or any CLI agent

Cursor, Windsurf, or IDE-based agents

Claude.ai, ChatGPT, Gemini, or any web AI

Models & Context

Recommended Models

Context Window

Pro tips for best results

Ready to try API Design Reviewer?