design-apis

name	design-apis
source	botcore
description	Provides API design guidance for REST, GraphQL, and gRPC services covering naming conventions, resource modeling, versioning strategies, error handling (RFC 9457), pagination patterns, OpenAPI 3.1 specification authoring, security (OAuth 2.1, rate limiting), and agent-friendly design patterns including MCP tool integration. Use when designing new APIs, reviewing API contracts, choosing between REST/GraphQL/gRPC, implementing error handling or pagination, writing OpenAPI specs, or making APIs consumable by AI agents. Triggers: API design, REST, GraphQL, gRPC, OpenAPI, error handling, pagination, versioning, API security, agent-friendly API, MCP tools, API-first.
version	1.0.0
triggers	["API design","REST API","GraphQL","gRPC","protobuf","OpenAPI","API error handling","pagination","API versioning","API security","rate limiting","OAuth","agent-friendly API","MCP tools","API-first","API contract","API documentation"]
portable	true

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 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.