API Architect Guru

An autonomous agent that designs robust, scalable APIs — defining resource models, endpoint hierarchies, versioning strategies, authentication schemes, and documentation standards for REST, GraphQL, and gRPC architectures.

When to Use This Agent

Choose API Architect Guru when:

• You are designing a new API from scratch and need consistent resource modeling
• Your existing API has grown organically and needs restructuring
• You need to choose between REST, GraphQL, and gRPC for your use case
• You want comprehensive API design including versioning, auth, rate limiting, and pagination

Consider alternatives when:

• You need to document an existing API (use an API documenter agent)
• You need to implement specific endpoints (use a backend developer agent)
• Your API is purely internal with a single consumer (keep it simple)

Quick Start

Copy
# .claude/agents/api-architect.yml
name: api-architect-guru
description: Design scalable API architectures
agent_prompt: |
  You are an API Architect. When designing APIs:

  1. Understand the domain model and consumer needs
  2. Choose the right API style (REST, GraphQL, gRPC)
  3. Design resource hierarchy and URL structure
  4. Define authentication and authorization schemes
  5. Plan versioning, pagination, filtering, and error handling
  6. Document with OpenAPI spec and usage examples

  Design principles:
  - Consistent naming and conventions across all endpoints
  - Consumer-driven design (optimize for the client, not the server)
  - Backward compatibility by default
  - Error responses as useful as success responses

Example invocation:

Copy
claude "Design a REST API for an e-commerce platform with products, orders, users, and reviews"

Sample API design output:

API Design — E-Commerce Platform
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Base URL: https://api.store.com/v1

Resources:
  /products                    GET (list), POST (create)
  /products/:id                GET, PUT, PATCH, DELETE
  /products/:id/reviews        GET, POST
  /products/:id/variants       GET, POST

  /orders                      GET (list), POST (create)
  /orders/:id                  GET, PATCH (update status)
  /orders/:id/items            GET
  /orders/:id/payments         POST, GET

  /users/me                    GET, PATCH
  /users/me/orders             GET
  /users/me/addresses          GET, POST, PUT, DELETE

Authentication: Bearer token (JWT)
  - Public: GET /products, GET /products/:id
  - Authenticated: POST /orders, GET /users/me
  - Admin: POST /products, DELETE /products/:id

Pagination: Cursor-based
  GET /products?cursor=abc123&limit=20

Error Format:
  { "error": { "code": "PRODUCT_NOT_FOUND", "message": "...", "details": {} } }

Core Concepts

API Style Selection

Factor	REST	GraphQL	gRPC
Multiple consumers	Good	Excellent	Moderate
Real-time data	Requires SSE/WS	Subscriptions	Streaming
Mobile clients	Good (over-fetching)	Excellent (exact data)	Excellent (binary)
Microservices	Good	Moderate	Excellent
Learning curve	Low	Medium	High
Caching	HTTP caching	Complex	Custom
File upload	Multipart	Complex	Streaming

RESTful URL Design Patterns

Resource Hierarchy:
  /api/v1/{resource}                    → Collection
  /api/v1/{resource}/{id}               → Single item
  /api/v1/{resource}/{id}/{sub-resource} → Nested collection

  Examples:
  GET  /api/v1/products                  → List products
  POST /api/v1/products                  → Create product
  GET  /api/v1/products/p_abc123         → Get product
  PUT  /api/v1/products/p_abc123         → Replace product
  PATCH /api/v1/products/p_abc123        → Update product fields
  DELETE /api/v1/products/p_abc123       → Delete product
  GET  /api/v1/products/p_abc123/reviews → List product reviews

  Query Parameters:
  ?sort=-created_at                      → Sort descending by date
  ?filter[status]=active                 → Filter by status
  ?fields=id,name,price                  → Sparse fieldsets
  ?include=reviews,variants              → Include related resources
  ?cursor=eyJpZCI6MTAwfQ&limit=20        → Cursor pagination

Error Response Design

Copy
// Consistent error format
interface APIError {
  error: {
    code: string;          // Machine-readable: "VALIDATION_ERROR"
    message: string;       // Human-readable: "Email is required"
    status: number;        // HTTP status code: 422
    details?: {
      field?: string;      // Which field failed: "email"
      reason?: string;     // Why: "must be a valid email address"
      help?: string;       // Link to docs
    }[];
    requestId: string;     // For support debugging: "req_abc123"
  };
}

// Standard error codes
const ERROR_CODES = {
  VALIDATION_ERROR: 422,
  NOT_FOUND: 404,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  RATE_LIMITED: 429,
  CONFLICT: 409,
  INTERNAL_ERROR: 500
};

Configuration

Option	Type	Default	Description
apiStyle	string	"rest"	Style: rest, graphql, grpc
versioning	string	"url-prefix"	Strategy: url-prefix, header, query-param
authentication	string	"jwt"	Auth: jwt, api-key, oauth2, none
pagination	string	"cursor"	Pagination: cursor, offset, keyset
generateOpenAPI	boolean	true	Output OpenAPI 3.1 spec
includeExamples	boolean	true	Include request/response examples

Best Practices

1. Use nouns for resources, not verbs — Endpoints should be /orders not /getOrders or /createOrder. The HTTP method (GET, POST, PUT, DELETE) already expresses the action. Verbs in URLs indicate the API is RPC-style, not RESTful, which makes it harder to learn and inconsistent across endpoints.

2. Use cursor-based pagination for large datasets — Offset pagination (?page=5&limit=20) breaks when data is inserted or deleted between pages. Cursor pagination (?cursor=abc123&limit=20) is stable, performant (no OFFSET scan), and works with real-time data. Only use offset pagination for static datasets where page numbers matter to users.

3. Return the created/updated resource in the response — After a POST or PATCH, return the full resource in the response body. This saves the client a second GET request and ensures they have the server-generated fields (ID, timestamps, computed values). Include the resource's canonical URL in the Location header.

4. Version from day one, even if you only have v1 — Adding versioning later requires coordinating all clients to update simultaneously. Start with /v1/ in the URL path and document your version deprecation policy. When v2 ships, v1 continues working for a defined sunset period.

5. Make error responses as useful as success responses — An error response with { "error": "Bad request" } is useless. Include the specific field that failed validation, the constraint that was violated, and ideally a link to documentation. Good error messages reduce support tickets and improve developer experience.

Common Issues

API design becomes inconsistent as more endpoints are added — Early endpoints follow one naming convention, later ones follow another. Create an API style guide document covering naming (plural nouns, kebab-case), response format, error structure, and authentication patterns. Review every new endpoint against the style guide before merging.

Breaking changes deployed without versioning — Removing a response field or changing its type breaks existing clients. Use additive changes only within a version: add new fields, add new endpoints, but never remove or rename existing ones. When breaking changes are unavoidable, create a new API version and deprecate the old one with a sunset date.

N+1 query problem from nested resource requests — The client calls GET /orders, then GET /orders/:id/items for each order, creating N+1 API calls. Add ?include=items support (JSON:API style) or implement a GraphQL layer for clients that need flexible data fetching. Alternatively, create purpose-built endpoints like GET /orders?expand=items that return nested data in a single request.