api-designer

Designing APIs

Expert guidance for designing REST, GraphQL, and gRPC APIs with modern best practices, agent-friendly patterns, and production-ready conventions.

Capabilities

1. REST API Design -- Resource naming, HTTP methods, status codes, headers, HATEOAS, and bulk/async operations
2. GraphQL Schema Design -- Type system, mutations, connections, error handling, and schema evolution
3. gRPC Service Design -- Protobuf style guide, service patterns, streaming, and well-known types
4. Error Handling -- RFC 9457 Problem Details, error code registries, and retry guidance
5. Versioning -- URI/header/query strategies, lifecycle management, deprecation, and migration
6. Pagination and Filtering -- Offset, cursor, and keyset pagination with sorting and search
7. Security -- OAuth 2.1, API keys, JWT validation, rate limiting, and OWASP API Top 10
8. Agent-Friendly Design -- MCP integration, OpenAPI for tool generation, composable workflows, idempotency
9. OpenAPI Specification -- API-first methodology, 3.1 authoring, linting, and documentation generation

Routing Logic

Request type	Load reference
REST resource design, HTTP methods, status codes, headers	references/rest-patterns.md
GraphQL schema, mutations, connections, subscriptions	references/graphql-patterns.md
gRPC services, protobuf style, streaming patterns	references/grpc-patterns.md
Error responses, RFC 9457, error codes, retry logic	references/error-handling.md
Versioning approaches, deprecation, migration	references/versioning-strategies.md
Pagination, filtering, sorting, search	references/pagination-and-filtering.md
Authentication, authorization, rate limiting, transport security	references/security-patterns.md
Agent consumption, MCP tools, composability, OpenAPI for agents	references/agent-friendly-apis.md
OpenAPI 3.1, API-first workflow, linting, documentation	references/openapi-and-documentation.md

Core Principles

1. API-First Design

Design the API contract before writing implementation code. The OpenAPI (REST), GraphQL schema, or Protobuf definition is the source of truth.

Workflow: Requirements -> Contract design -> Stakeholder review -> Lint/validate -> Mock -> Implement -> Test conformance -> Publish docs.

Use OpenAPI 3.1 for REST APIs, AsyncAPI 3.0 for event-driven APIs, and Protobuf with buf lint for gRPC.

2. Choose the Right Paradigm

Factor	REST	GraphQL	gRPC
Best for	CRUD, public APIs, broad adoption	Flexible queries, frontend-driven	Microservices, high performance
Data fetching	Fixed endpoints	Client-specified fields	Strongly typed messages
Protocol	HTTP/1.1+ JSON	HTTP POST JSON	HTTP/2 Protobuf
Caching	Native HTTP caching	Requires custom caching	No native HTTP caching
Agent-friendly	High (URL-based, widely supported)	Medium (requires query construction)	Low without gRPC-Gateway
Schema	OpenAPI 3.1	GraphQL SDL (introspectable)	Protobuf definitions
Real-time	Webhooks, SSE	Subscriptions (WebSocket)	Bidirectional streaming

Decision guide:

• Public API or AI agent consumers -> REST
• Frontend with diverse data needs -> GraphQL
• Internal microservices needing speed -> gRPC
• Multiple paradigms are valid; expose gRPC internally with a REST gateway for external consumers

3. Naming Conventions

REST URLs:

• Plural nouns for collections: /users, /order-items
• No verbs in paths: POST /users not POST /createUser
• Kebab-case for multi-word segments: /order-items not /orderItems
• Max 3 levels of nesting: /users/{id}/orders (flatten beyond that)

GraphQL: PascalCase types, camelCase fields, SCREAMING_SNAKE_CASE enums, Input/Payload suffixes.

Protobuf: PascalCase messages/services, snake_case fields, ENUM_PREFIX_VALUE enums, Service suffix.

4. Error Handling

Use RFC 9457 Problem Details for all REST error responses:

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 422,
  "detail": "The email field must be a valid email address.",
  "errors": [
    { "field": "email", "code": "INVALID_FORMAT", "message": "Must be a valid email" }
  ]
}

Rules:

• Content-Type: application/problem+json
• Define an error code registry and publish it
• Include field-level validation errors for 400/422 responses
• Include retry_after_seconds for 429 and transient 5xx errors
• Distinguish retryable (408, 429, 500, 502, 503, 504) from non-retryable (400, 401, 403, 404, 422) errors
• For agents: use stable string error codes, not just HTTP status codes

5. Versioning

Use URI path versioning (/api/v1/) for public and agent-consumed APIs. It is the most explicit and discoverable approach.

When to bump the version: Removing fields, renaming fields, changing types, changing auth, changing error format.

When NOT to bump: Adding new fields, adding new endpoints, adding optional parameters, fixing bugs to match documented behavior.

Deprecation: Set Deprecation: true and Sunset: {date} headers. Give consumers 6+ months notice. Return 410 Gone after sunset.

6. Pagination

Default to cursor-based pagination for most APIs:

GET /api/v1/users?limit=20&after=eyJpZCI6MTAwfQ

{
  "data": [ ... ],
  "pagination": {
    "has_next": true,
    "next_cursor": "eyJpZCI6MTIwfQ"
  }
}

• Enforce a maximum page size (100 is typical)
• Always return has_next and navigation cursor/link
• Return empty array for zero results, never null
• Use offset-based only when random page access is required

7. Security

Authentication: OAuth 2.1 with Authorization Code + PKCE for user context. Client Credentials for service-to-service. API keys for application identification only (not user auth).

Authorization: Scope-based (read:users, write:users) checked at middleware layer. RBAC or ABAC for fine-grained control.

Rate limiting: Per-consumer (API key or token), not global. Return X-RateLimit-* headers on every response. Return 429 with Retry-After header when exceeded.

Transport: TLS 1.2+ required. HSTS header. CORS configured per-origin (never wildcard for authenticated APIs).

8. Agent-Friendly Design

Design every API as if an AI agent is a first-class consumer:

• OpenAPI spec at stable URL -- Serve at /openapi.json. Agents auto-generate tools from it.
• operationId as tool name -- Use clear verb-noun IDs: listUsers, createOrder. These become function names.
• Examples in every schema -- Agents use examples to construct valid requests.
• HATEOAS links -- Include links and allowed_actions so agents can navigate without hardcoding URLs.
• Idempotency keys -- Accept Idempotency-Key header on POST/PATCH for safe agent retries.
• Prefixed IDs -- Use usr_123, ord_456 so agents can identify resource types from IDs alone.
• Consistent response shapes -- Same envelope for success, error, and collection responses.
• Document workflows -- Show multi-step API call chains in docs; agents use these to plan.

9. MCP Tool Exposure

When wrapping APIs as MCP tools for AI agents:

• One tool per distinct action (not one mega-tool)
• Simple parameter types (str, int, bool) over complex objects
• Descriptions under 50 tokens each
• Include valid values and defaults in the description
• Return structured Markdown, not raw JSON

Quick Reference

REST Endpoint Template

GET    /api/v1/{resource}              -> List (200, paginated)
POST   /api/v1/{resource}              -> Create (201 + Location header)
GET    /api/v1/{resource}/{id}         -> Read (200)
PUT    /api/v1/{resource}/{id}         -> Replace (200)
PATCH  /api/v1/{resource}/{id}         -> Partial update (200)
DELETE /api/v1/{resource}/{id}         -> Remove (204)
POST   /api/v1/{resource}/{id}/{action} -> Custom action (200)

Standard Headers

Request:  Authorization, Content-Type, Accept, Idempotency-Key, X-Request-ID
Response: Content-Type, Location, ETag, Cache-Control, Retry-After,
          X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset,
          X-Request-ID, Deprecation, Sunset

Status Code Cheat Sheet

200 OK              - GET/PUT/PATCH success
201 Created         - POST success (+ Location)
202 Accepted        - Async operation queued
204 No Content      - DELETE success
400 Bad Request     - Malformed input
401 Unauthorized    - Missing/invalid auth
403 Forbidden       - Insufficient permissions
404 Not Found       - Resource doesn't exist
409 Conflict        - State conflict
422 Unprocessable   - Validation failure
429 Too Many        - Rate limited (+ Retry-After)
500 Internal Error  - Server failure
503 Unavailable     - Temporary outage (+ Retry-After)

Checklist

Before shipping an API, verify:

• API contract (OpenAPI/GraphQL SDL/Protobuf) written and reviewed before implementation
• All endpoints have operationId, summary, description, and examples
• Naming conventions are consistent (plural nouns, kebab-case URLs, appropriate casing per paradigm)
• Error responses follow RFC 9457 with stable error codes and field-level validation details
• Pagination implemented with maximum page size enforced and navigation metadata included
• Versioning strategy chosen and documented; deprecation policy defined
• Authentication and authorization implemented (OAuth 2.1 / API keys / scopes)
• Rate limiting active with X-RateLimit-* headers

---

Content truncated.