API Design Framework

API Design Framework

Overview

This skill provides comprehensive guidance for designing robust, scalable, and developer-friendly APIs. Whether building REST, GraphQL, or gRPC services, this framework ensures consistency, usability, and maintainability.

When to use this skill:

• Designing new API endpoints or services
• Establishing API conventions for a team or organization
• Reviewing API designs for consistency and best practices
• Migrating or versioning existing APIs
• Creating API documentation (OpenAPI, AsyncAPI)
• Choosing between REST, GraphQL, or gRPC

API Design Principles

1. Developer Experience First

APIs should be intuitive and self-documenting:

• Clear, consistent naming conventions
• Predictable behavior and responses
• Comprehensive documentation
• Helpful error messages

2. Consistency Over Cleverness

Follow established patterns rather than inventing new ones:

• Standard HTTP methods and status codes (REST)
• Conventional query structures (GraphQL)
• Idiomatic proto definitions (gRPC)

3. Evolution Without Breaking Changes

Design for change from day one:

• API versioning strategy
• Backward compatibility considerations
• Deprecation policies
• Migration paths

4. Performance by Design

Consider performance implications:

• Pagination for large datasets
• Filtering and partial responses
• Caching strategies
• Rate limiting

REST API Design

Resource Naming Conventions

Use plural nouns for resources:

✅ GET /users
✅ GET /users/123
✅ GET /users/123/orders

❌ GET /user
❌ GET /getUser
❌ GET /user/123

Use hierarchical relationships:

✅ GET /users/123/orders          # Orders for specific user
✅ GET /teams/5/members           # Members of specific team
✅ POST /projects/10/tasks        # Create task in project 10

❌ GET /userOrders/123            # Flat structure
❌ GET /orders?userId=123         # Query param for relationship

Use kebab-case for multi-word resources:

✅ /shopping-carts
✅ /order-items
✅ /user-preferences

❌ /shoppingCarts    (camelCase)
❌ /shopping_carts   (snake_case)
❌ /ShoppingCarts    (PascalCase)

HTTP Methods (Verbs)

*PATCH can be designed to be idempotent

Status Codes

Success (2xx)

• 200 OK: Successful GET, PUT, PATCH, or DELETE
• 201 Created: Successful POST (include Location header)
• 202 Accepted: Request accepted, processing async
• 204 No Content: Successful DELETE or PUT with no response body

Client Errors (4xx)

• 400 Bad Request: Invalid request body or parameters
• 401 Unauthorized: Missing or invalid authentication
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource doesn't exist
• 405 Method Not Allowed: HTTP method not supported for resource
• 409 Conflict: Resource conflict (e.g., duplicate)
• 422 Unprocessable Entity: Validation failed
• 429 Too Many Requests: Rate limit exceeded

Server Errors (5xx)

• 500 Internal Server Error: Generic server error
• 502 Bad Gateway: Upstream service error
• 503 Service Unavailable: Temporary unavailability
• 504 Gateway Timeout: Upstream timeout

Request/Response Formats

Request Body (POST/PUT/PATCH):

POST /users
Content-Type: application/json

{
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "developer"
}

Success Response:

HTTP/1.1 201 Created
Location: /users/123
Content-Type: application/json

{
  "id": 123,
  "email": "jane@example.com",
  "name": "Jane Smith",
  "role": "developer",
  "created_at": "December 2025T10:30:00Z",
  "updated_at": "December 2025T10:30:00Z"
}

Error Response (Standard Format):

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Email is already registered",
        "code": "DUPLICATE_EMAIL"
      },
      {
        "field": "name",
        "message": "Name must be at least 2 characters",
        "code": "NAME_TOO_SHORT"
      }
    ],
    "timestamp": "December 2025T10:30:00Z",
    "request_id": "req_abc123"
  }
}

Pagination

Cursor-Based Pagination (Recommended):

GET /users?cursor=eyJpZCI6MTIzfQ&limit=20

Response:
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTQzfQ",
    "has_more": true
  }
}

Pros: Consistent results even as data changes Use for: Large datasets, real-time data, infinite scroll

Offset-Based Pagination:

GET /users?page=2&per_page=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 2,
    "per_page": 20,
    "total": 487,
    "total_pages": 25
  }
}

Pros: Easy to understand, supports "jump to page N" Use for: Small datasets, admin panels, known bounds

Filtering and Sorting

Filtering:

GET /users?status=active&role=developer&created_after=2025-01-01
GET /products?price_min=10&price_max=100&category=electronics

Sorting:

GET /users?sort=created_at:desc
GET /users?sort=-created_at              # Minus prefix for descending
GET /users?sort=name:asc,created_at:desc # Multiple fields

Field Selection (Partial Response):

GET /users?fields=id,name,email          # Only specified fields
GET /users/123?exclude=password_hash     # All except specified

API Versioning

Strategy 1: URI Versioning (Recommended)

✅ /api/v1/users
✅ /api/v2/users

Pros: Clear, easy to test, cache-friendly
Cons: Verbose URLs

Strategy 2: Header Versioning

GET /api/users
Accept: application/vnd.company.v2+json

Pros: Clean URLs
Cons: Harder to test, not visible in URL

Strategy 3: Query Parameter

GET /api/users?version=2

Pros: Simple
Cons: Can be forgotten, mixes with business logic params

Best Practice: URI versioning for public APIs, header versioning for internal services

Rate Limiting

Response Headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1635724800

Response when exceeded:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retry_after": 3600
  }
}

Authentication & Authorization

Bearer Token (JWT):

GET /users/me
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key:

GET /users
X-API-Key: sk_live_abc123...

Basic Auth (avoid for production):

GET /users
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=

GraphQL API Design

Schema Design Principles

1. Nullable by Default

type User {
  id: ID!              # Non-null (required)
  email: String!       # Non-null
  name: String         # Nullable (optional)
  avatar: String       # Nullable
}

2. Use Connections for Lists

type Query {
  users(first: Int, after: String): UserConnection!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

3. Input Types for Mutations

input CreateUserInput {
  email: String!
  name: String!
  role: UserRole!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

type CreateUserPayload {
  user: User!
  errors: [UserError!]
}

type UserError {
  field: String!
  message: String!
  code: String!
}

Query Design

Fetch single resource:

query GetUser {
  user(id: "123") {
    id
    name
    email
    posts {
      id
      title
    }
  }
}

Fetch list with filters:

query GetUsers {
  users(
    first: 10
    after: "cursor123"
    filter: { role: DEVELOPER, status: ACTIVE }
  ) {
    edges {
      node {
        id
        name
        email
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Error Handling

Field-Level Errors:

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
}

type CreateUserPayload {
  user: User
  errors: [UserError!]
}

Response:

{
  "data": {
    "createUser": {
      "user": null,
      "errors": [
        {
          "field": "email",
          "message": "Email is already taken",
          "code": "DUPLICATE_EMAIL"
        }
      ]
    }
  }
}

gRPC API Design

Proto File Structure

user.proto:

syntax = "proto3";

package company.user.v1;

import "google/protobuf/timestamp.proto";
import "google/protobuf/empty.proto";

// User service definition
service UserService {
  // Get user by ID
  rpc GetUser(GetUserRequest) returns (GetUserResponse);

  // List users with pagination
  rpc ListUsers(ListUsersRequest) returns (ListUsersResponse);

  // Create new user
  rpc CreateUser(CreateUserRequest) returns (CreateUserResponse);

  // Update user
  rpc UpdateUser(UpdateUserRequest) returns (UpdateUserResponse);

  // Delete user
  rpc DeleteUser(DeleteUserRequest) returns (google.protobuf.Empty);

  // Stream updates (server streaming)
  rpc WatchUsers(WatchUsersRequest) returns (stream UserEvent);
}

// Messages
message User {
  string id = 1;
  string email = 2;
  string name = 3;
  UserRole role = 4;
  google.protobuf.Timestamp created_at = 5;
  google.protobuf.Timestamp updated_at = 6;
}

enum UserRole {
  USER_ROLE_UNSPECIFIED = 0;
  USER_ROLE_ADMIN = 1;
  USER_ROLE_DEVELOPER = 2;
  USER_ROLE_VIEWER = 3;
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

message ListUsersRequest {
  int32 page_size = 1;
  string page_token = 2;
  string filter = 3;  // e.g., "role=DEVELOPER AND status=ACTIVE"
}

message ListUsersResponse {
  repeated User users = 1;
  string next_page_token = 2;
  int32 total_size = 3;
}

message CreateUserRequest {
  string email = 1;
  string name = 2;
  UserRole role = 3;
}

message CreateUserResponse {
  User user = 1;
}

Error Handling

Use gRPC status codes:

// OK: Success
// CANCELLED: Client cancelled
// INVALID_ARGUMENT: Invalid request (400 equivalent)
// NOT_FOUND: Resource not found (404 equivalent)
// ALREADY_EXISTS: Duplicate (409 equivalent)
// PERMISSION_DENIED: Forbidden (403 equivalent)
// UNAUTHENTICATED: Auth required (401 equivalent)
// RESOURCE_EXHAUSTED: Rate limit (429 equivalent)
// INTERNAL: Server error (500 equivalent)

API Documentation

OpenAPI 3.1 Structure

See /templates/openapi-template.yaml for complete example.

Key sections:

• info: API metadata (title, version, description)
• servers: Base URLs for different environments
• paths: Endpoints with operations
• components: Reusable schemas, responses, parameters
• security: Authentication schemes

AsyncAPI 3.0 (Event-Driven)

For documenting message-based APIs (Kafka, RabbitMQ, WebSockets).

See /templates/asyncapi-template.yaml for complete example.

Best Practices

1. Use Standard Media Types

Content-Type: application/json          # JSON
Content-Type: application/xml           # XML
Content-Type: application/protobuf      # Protocol Buffers
Content-Type: application/octet-stream  # Binary data

2. HATEOAS (Optional for REST)

Include links for related resources:

{
  "id": 123,
  "name": "Jane Smith",
  "_links": {
    "self": { "href": "/users/123" },
    "orders": { "href": "/users/123/orders" },
    "avatar": { "href": "/users/123/avatar" }
  }
}

3. Idempotency Keys

For preventing duplicate operations:

POST /payments
Idempotency-Key: unique-request-id-123

4. Bulk Operations

POST /users/bulk-create
POST /users/bulk-update
POST /users/bulk-delete

5. Webhooks

Document webhook payloads and retry logic:

POST https://client.example.com/webhook
X-Webhook-Signature: sha256=abc123...

{
  "event": "user.created",
  "data": { ... },
  "timestamp": "December 2025T10:30:00Z"
}

Common Pitfalls

❌ Using verbs in URLs

Bad:  POST /createUser
Good: POST /users

❌ Inconsistent naming

Bad:  /users, /userOrders, /user_preferences
Good: /users, /orders, /preferences

❌ Ignoring HTTP methods

Bad:  POST /users/123/delete
Good: DELETE /users/123

❌ Exposing implementation details

Bad:  /users-table, /get-user-from-db
Good: /users, /users/123

❌ Generic error messages

Bad:  { "error": "Something went wrong" }
Good: { "error": { "code": "DUPLICATE_EMAIL", "message": "Email already exists" }}

Frontend API Integration (2025 Patterns)

This section covers how frontend applications should consume APIs with type safety and resilience.

Runtime Validation with Zod

CRITICAL: TypeScript types are erased at runtime. API responses MUST be validated:

import { z } from 'zod'

// Define schema matching API contract
const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  name: z.string(),
  role: z.enum(['admin', 'developer', 'viewer']),
  created_at: z.string().datetime(),
})

const UsersResponseSchema = z.object({
  data: z.array(UserSchema),
  pagination: z.object({
    next_cursor: z.string().nullable(),
    has_more: z.boolean(),
  }),
})

type User = z.infer<typeof UserSchema>
type UsersResponse = z.infer<typeof UsersResponseSchema>

// Fetch with validation
async function fetchUsers(cursor?: string): Promise<UsersResponse> {
  const url = cursor ? `/api/v1/users?cursor=${cursor}` : '/api/v1/users'
  const response = await fetch(url)

  if (!response.ok) {
    throw new ApiError(response.status, await response.text())
  }

  const data = await response.json()
  return UsersResponseSchema.parse(data) // Runtime validation!
}

Anti-patterns to avoid:

// ❌ NEVER: Trust API response types blindly
const data = await response.json() as User  // Unsafe cast!

// ❌ NEVER: Skip validation "because backend is typed"
const user: User = await response.json()    // Runtime crash waiting to happen

// ✅ ALWAYS: Validate at the boundary
const user = UserSchema.parse(await response.json())

Request Interceptors (ky/axios)

Use interceptors for cross-cutting concerns:

import ky from 'ky'

// Create configured client
export const api = ky.create({
  prefixUrl: import.meta.env.VITE_API_URL,
  timeout: 30000,
  retry: {
    limit: 2,
    methods: ['get', 'head', 'options'],
    statusCodes: [408, 429, 500, 502, 503, 504],
    backoffLimit: 3000,
  },
  hooks: {
    beforeRequest: [
      // Auth injection
      async (request) => {
        const token = await getAccessToken()
        if (token) {
          request.headers.set('Authorization', `Bearer ${token}`)
        }
      },
      // Request ID for tracing
      (request) => {
        request.headers.set('X-Request-ID', crypto.randomUUID())
      },
    ],
    afterResponse: [
      // Token refresh on 401
      async (request, options, response) => {
        if (response.status === 401) {
          const newToken = await refreshToken()
          if (newToken) {
            request.headers.set('Authorization', `Bearer ${newToken}`)
            return ky(request, options)
          }
        }
        return response
      },
    ],
    beforeError: [
      // Enrich error with response body
      async (error) => {
        const { response } = error
        if (response) {
          try {
            const body = await response.json()
            error.message = body.error?.message || error.message
            ;(error as any).code = body.error?.code
          } catch {
            // Response not JSON, keep original error
          }
        }
        return error
      },
    ],
  },
})

// Usage with Zod validation
export async function getUsers(cursor?: string): Promise<UsersResponse> {
  const searchParams = cursor ? { cursor } : undefined
  const data = await api.get('users', { searchParams }).json()
  return UsersResponseSchema.parse(data)
}

Error Enrichment Pattern

Structured error handling with API error codes:

// Custom API error class
class ApiError extends Error {
  constructor(
    public status: number,
    public code: string,
    message: string,
    public details?: Array<{ field: string; message: string }>
  ) {
    super(message)
    this.name = 'ApiError'
  }

  get isValidationError(): boolean {
    return this.status === 422
  }

  get isAuthError(): boolean {
    return this.status === 401 || this.status === 403
  }

  get isRateLimited(): boolean {
    return this.status === 429
  }
}

// Error parsing from API response
const ApiErrorSchema = z.object({
  error: z.object({
    code: z.string(),
    message: z.string(),
    details: z.array(z.object({
      field: z.string(),
      message: z.string(),
    })).optional(),
  }),
})

function parseApiError(status: number, body: unknown): ApiError {
  const parsed = ApiErrorSchema.safeParse(body)
  if (parsed.success) {
    return new ApiError(
      status,
      parsed.data.error.code,
      parsed.data.error.message,
      parsed.data.error.details
    )
  }
  return new ApiError(status, 'UNKNOWN_ERROR', 'An unexpected error occurred')
}

Integration with TanStack Query

import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'

// Query with Zod validation built-in
export function useUsers(cursor?: string) {
  return useQuery({
    queryKey: ['users', { cursor }],
    queryFn: () => getUsers(cursor),
    staleTime: 30_000, // 30 seconds
  })
}

// Mutation with optimistic update
export function useCreateUser() {
  const queryClient = useQueryClient()

  return useMutation({
    mutationFn: (input: CreateUserInput) =>
      api.post('users', { json: input }).json().then(UserSchema.parse),
    onMutate: async (newUser) => {
      await queryClient.cancelQueries({ queryKey: ['users'] })
      // Optimistic update...
    },
    onSettled: () => {
      queryClient.invalidateQueries({ queryKey: ['users'] })
    },
  })
}

Integration with Agents

Backend System Architect

• Uses this framework when designing new APIs
• References patterns for consistency across services
• Creates OpenAPI specifications from templates

Frontend UI Developer

• Reviews API contracts before implementation
• Provides feedback on developer experience
• Integrates with APIs following documented patterns
• Uses Frontend API Integration patterns for type-safe consumption

Code Quality Reviewer

• Validates API designs against this framework
• Ensures OpenAPI docs are accurate and complete
• Checks for REST/GraphQL/gRPC best practices
• Verifies frontend Zod schemas match backend contracts

Skill Version: 1.1.0 Last Updated: December 2025 Maintained by: YG Starter Team

Changelog

v1.1.0 (December 2025)

• Added Frontend API Integration (2025 Patterns) section
• Added Zod runtime validation patterns for API responses
• Added request interceptors with ky (auth, retry, error enrichment)
• Added ApiError class with structured error handling
• Added TanStack Query integration examples
• Updated agent integration notes for frontend patterns

Converted and distributed by TomeVault — claim your Tome and manage your conversions.