API Designer Mentor

An autonomous agent that mentors developers through API design best practices — reviewing endpoint structures, request/response schemas, and helping evolve APIs with backward compatibility and consumer-first thinking.

When to Use This Agent

Choose API Designer Mentor when:

• You are reviewing API designs and want feedback on consistency and usability
• Junior developers need guidance on RESTful design conventions
• You want to evaluate an API design against industry standards before implementation
• Your team needs a consistent API style guide enforced across multiple services

Consider alternatives when:

• You need to architect a complete new API from scratch (use an API architect agent)
• You need automated API documentation generation (use an API documenter agent)
• You are debugging API implementation bugs, not design issues

Quick Start

Copy
# .claude/agents/api-designer-mentor.yml
name: api-designer-mentor
description: Review and mentor API design decisions
agent_prompt: |
  You are an API Design Mentor. When reviewing API designs:

  1. Evaluate naming conventions (nouns, plural, consistent casing)
  2. Check HTTP method usage (GET=read, POST=create, PUT=replace, PATCH=update)
  3. Review response schemas for consistency and completeness
  4. Assess error handling patterns
  5. Verify pagination, filtering, and sorting design
  6. Check backward compatibility of changes

  Provide feedback as a mentor: explain WHY something should change,
  not just WHAT to change. Reference industry standards (JSON:API, OpenAPI).

Example invocation:

Copy
claude "Review this API design for our user management service and suggest improvements"

Sample review output:

API Design Review — User Management
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Overall Score: B+ (Good with minor improvements needed)

✓ Good Practices:
  - Consistent plural resource names
  - Proper use of HTTP methods
  - Meaningful error codes

⚠ Improvements Suggested:
  1. POST /users/login → POST /auth/sessions
     Why: Login creates a session, not a user. Separate auth from user CRUD.

  2. GET /users?page=3 → GET /users?cursor=abc&limit=20
     Why: Offset pagination is unstable with concurrent writes.

  3. DELETE /users/:id returns 200 → should return 204 No Content
     Why: DELETE with no response body should use 204 by convention.

  4. Missing: Rate limit headers (X-RateLimit-Remaining)
     Why: Clients need to know their quota to implement backoff.

Core Concepts

API Design Review Checklist

Category	Check	Standard
Naming	Plural nouns, kebab-case	/user-profiles not /getUserProfile
Methods	Correct HTTP verb usage	POST=create, PUT=replace, PATCH=partial
Status Codes	Semantic HTTP codes	201 for create, 204 for delete, 422 for validation
Errors	Consistent error envelope	{ error: { code, message, details } }
Pagination	Stable cursor-based	?cursor=x&limit=20 with next/prev links
Versioning	Explicit version strategy	URL prefix /v1/ or Accept header
Auth	Token-based, scoped	Bearer JWT with role/permission claims

Design Pattern Library

Copy
// Pattern: Consistent response envelope
interface APIResponse<T> {
  data: T;                          // The actual payload
  meta?: {
    total?: number;                 // Total items (for lists)
    cursor?: string;                // Pagination cursor
    rateLimit?: {
      remaining: number;
      resetAt: string;
    };
  };
  links?: {
    self: string;
    next?: string;
    prev?: string;
  };
}

// Pattern: Partial update with PATCH
// Only send fields that changed
// PATCH /api/v1/users/usr_123
// Body: { "name": "New Name" }
// Response: full updated resource

// Pattern: Bulk operations
// POST /api/v1/users/bulk
// Body: { "operations": [{ "method": "create", "data": {...} }, ...] }
// Response: { "results": [{ "status": 201, "data": {...} }, ...] }

Common Anti-Patterns

Anti-Pattern → Correct Approach:

  GET /getUsers          → GET /users
  POST /users/delete/5   → DELETE /users/5
  GET /users?action=list  → GET /users
  PUT /users/5 (partial)  → PATCH /users/5
  200 for all responses   → 201 (created), 204 (deleted), 422 (validation)
  { "success": true }     → HTTP 200 (status is in the HTTP code)
  { "data": null }        → HTTP 404 with error body

Configuration

Option	Type	Default	Description
strictness	string	"moderate"	Review strictness: lenient, moderate, strict
standard	string	"rest"	Design standard: rest, json-api, hal
checkBackwardCompat	boolean	true	Flag breaking changes
suggestAlternatives	boolean	true	Provide corrected designs
includeExamples	boolean	true	Add request/response examples
mentorStyle	string	"educational"	Feedback style: educational, terse, detailed

Best Practices

1. Teach the "why" behind every suggestion — Instead of "change POST /login to POST /sessions," explain: "Login creates a session resource. Modeling it as a resource creation (POST /sessions) lets you use DELETE /sessions for logout and GET /sessions for session listing, creating a consistent CRUD pattern."

2. Review API designs before any code is written — API design changes are cheap when they are on paper and expensive when they are in production with clients depending on them. Review the URL structure, request/response schemas, and error formats before writing the first line of implementation code.

3. Use real-world scenarios during review — Walk through the API design with concrete user stories: "A mobile client needs to display a product page with reviews. How many API calls does that require?" This reveals missing includes, unnecessary endpoints, and over-fetching problems.

4. Document every deviation from standards — If you choose to use a verb endpoint (POST /users/:id/activate) instead of a resource update (PATCH /users/:id { status: "active" }), document why. Future developers will assume it is a mistake and "fix" it unless the reasoning is recorded.

5. Review for consistency across the entire API surface — A single endpoint review misses cross-cutting inconsistencies. Review pagination, error formats, authentication, and naming conventions across all endpoints at once to ensure the API feels like one cohesive product rather than a patchwork.

Common Issues

Inconsistent response formats across endpoints — Some endpoints return { data: ... }, others return the resource directly, and some use { result: ... }. Define a response envelope standard and enforce it across all endpoints. A middleware layer that wraps all responses in the standard format is more reliable than relying on each developer to remember.

Breaking changes introduced without realizing it — Renaming a response field from userName to username breaks all clients parsing the old name. Add an API contract test suite that compares the current response schema against a baseline. Run it in CI to catch field removals, renames, and type changes before they merge.

API grows organically without a style guide — Without a written API style guide, each developer designs endpoints based on their own preferences, creating an inconsistent API. Create a living style guide covering naming, methods, status codes, error formats, pagination, and authentication. Require API design review against the style guide for every PR that adds or modifies endpoints.