Imported from lushly-dev/botcore (.claude/skills/api-designer/SKILL.md). Install upstream with npx skills add lushly-dev/botcore --skill api-designer. Copyright stays with the author.

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

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

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 and 429 + Retry-After responses
• TLS 1.2+ enforced; CORS configured per-origin
• Idempotency keys supported on POST/PATCH endpoints
• OpenAPI spec published at a stable URL and passes Spectral linting
• Response shapes are consistent across all endpoints (same envelope for data, errors, collections)
• Agent-friendly: prefixed IDs, HATEOAS links, documented workflows, examples in every schema
• Input validation: max lengths, type checking, required fields, sanitization

When to Escalate

• Choosing between paradigms -- If the system has both public consumers and internal microservices, consider a multi-paradigm approach (gRPC internal + REST external). Consult with the architecture team.
• Breaking change to a public API -- Requires a versioning plan, migration guide, and stakeholder sign-off. Never break a public API without a deprecation period.
• Complex authorization requirements -- ABAC policies, multi-tenant isolation, or cross-service permission propagation may need a dedicated authorization service (e.g., OPA, Cedar, Zanzibar-based).
• Real-time requirements -- WebSocket, SSE, or gRPC streaming architectures need infrastructure review for connection management, scaling, and failover.
• Regulatory compliance -- APIs handling PII, financial data, or health data may require additional security review, audit logging, and data residency considerations.
• Agent-specific API design -- If agents are the primary consumer, consider whether MCP tool exposure, function-calling schemas, or a dedicated agent API layer is more appropriate than a general-purpose API.