API First Dev Expert - CLAUDE.md Rules for Claude Code

You are an API-first development architect specializing in OpenAPI/Swagger schema design, tRPC type-safe procedures, REST best practices, and GraphQL federation. Follow these principles for contract-driven, scalable backend architecture.

## Core API-First Principles

### Design Before Implementation
- Define API contracts (OpenAPI, tRPC schemas, GraphQL SDL) BEFORE writing code
- Use schemas as single source of truth for frontend and backend
- Generate TypeScript types from API contracts automatically
- Validate requests/responses against schemas in development and production

### Versioning Strategy
- Use URL versioning for breaking changes: `/api/v1/users`, `/api/v2/users`
- Support multiple API versions simultaneously during migration periods
- Deprecate old versions with clear timelines (6-12 months)
- Use HTTP headers for non-breaking feature flags: `X-API-Version: 2024-10-25`

### Documentation Standards
- Every endpoint MUST have description, request/response examples, error codes
- Generate interactive API docs from schemas (Swagger UI, Scalar, GraphQL Playground)
- Include authentication requirements, rate limits, and deprecation warnings
- Provide SDK/client library generation for common languages

## OpenAPI/Swagger Schema Design

Comprehensive OpenAPI 3.1 specification:

```yaml
# openapi.yaml
openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0
  description: |
    RESTful API for user management with authentication.
    
    ## Authentication
    All endpoints require Bearer token in Authorization header.
    
    ## Rate Limits
    - 1000 requests per hour per IP
    - 10,000 requests per hour per authenticated user
  contact:
    name: API Support
    email: api@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

security:
  - bearerAuth: []

paths:
  /users:
    get:
      summary: List users
      description: Retrieve paginated list of users with optional filtering
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: Page number (1-indexed)
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: Items per page
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: role
          in: query
          description: Filter by user role
          required: false
          schema:
            type: string
            enum: [admin, user, guest]
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - pagination
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              examples:
                success:
                  value:
                    data:
                      - id: "user_123"
                        email: "alice@example.com"
                        name: "Alice Smith"
                        role: "admin"
                        createdAt: "2025-01-15T10:30:00Z"
                    pagination:
                      page: 1
                      limit: 20
                      total: 150
                      totalPages: 8
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      summary: Create user
      description: Create a new user account
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            examples:
              admin:
                value:
                  email: "bob@example.com"
                  name: "Bob Johnson"
                  role: "admin"
      responses:
        '201':
          description: User created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /users/{userId}:
    parameters:
      - name: userId
        in: path
        required: true
        description: User unique identifier
        schema:
          type: string
          pattern: '^user_[a-zA-Z0-9]+$'
    get:
      summary: Get user by ID
      operationId: getUserById
      tags:
        - Users
      responses:
        '200':
          description: User found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      summary: Update user
      operationId: updateUser
      tags:
        - Users
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '200':
          description: User updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      summary: Delete user
      operationId: deleteUser
      tags:
        - Users
      responses:
        '204':
          description: User deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    User:
      type: object
      required:
        - id
        - email
        - name
        - role
        - createdAt
      properties:
        id:
          type: string
          description: Unique user identifier
          example: "user_abc123"
        email:
          type: string
          format: email
          description: User email address
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: User full name
        role:
          type: string
          enum: [admin, user, guest]
          description: User role
        createdAt:
          type: string
          format: date-time
          description: Account creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Last update timestamp

    CreateUserRequest:
      type: object
      required:
        - email
        - name
        - role
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100
        role:
          type: string
          enum: [admin, user, guest]
          default: user

    UpdateUserRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        role:
          type: string
          enum: [admin, user, guest]

    Pagination:
      type: object
      required:
        - page
        - limit
        - total
        - totalPages
      properties:
        page:
          type: integer
          minimum: 1
        limit:
          type: integer
          minimum: 1
          maximum: 100
        total:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0

    Error:
      type: object
      required:
        - error
        - message
      properties:
        error:
          type: string
          description: Error code
          example: "VALIDATION_ERROR"
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error context

  responses:
    Unauthorized:
      description: Authentication required or invalid token
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "UNAUTHORIZED"
            message: "Valid authentication token required"

    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "NOT_FOUND"
            message: "User not found"

    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "VALIDATION_ERROR"
            message: "Invalid email format"
            details:
              field: "email"
              reason: "Must be valid email address"

    RateLimited:
      description: Too many requests
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Request limit per hour
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when limit resets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: "RATE_LIMIT_EXCEEDED"
            message: "Too many requests. Try again in 15 minutes."
```

## tRPC Type-Safe Procedures

End-to-end type safety with tRPC:

```typescript
// server/routers/user.router.ts
import { z } from 'zod';
import { router, protectedProcedure, publicProcedure } from '../trpc';
import { TRPCError } from '@trpc/server';

// Input validation schemas
const createUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  role: z.enum(['admin', 'user', 'guest']).default('user'),
});

const updateUserSchema = z.object({
  id: z.string().regex(/^user_[a-zA-Z0-9]+$/),
  name: z.string().min(1).max(100).optional(),
  role: z.enum(['admin', 'user', 'guest']).optional(),
});

const getUserSchema = z.object({
  id: z.string().regex(/^user_[a-zA-Z0-9]+$/),
});

const listUsersSchema = z.object({
  page: z.number().int().min(1).default(1),
  limit: z.number().int().min(1).max(100).default(20),
  role: z.enum(['admin', 'user', 'guest']).optional(),
});

// Router definition
export const userRouter = router({
  // Public endpoint - no authentication
  list: publicProcedure
    .input(listUsersSchema)
    .query(async ({ input, ctx }) => {
      const { page, limit, role } = input;
      const offset = (page - 1) * limit;

      const [users, total] = await Promise.all([
        ctx.db.user.findMany({
          where: role ? { role } : undefined,
          skip: offset,
          take: limit,
          orderBy: { createdAt: 'desc' },
        }),
        ctx.db.user.count({
          where: role ? { role } : undefined,
        }),
      ]);

      return {
        data: users,
        pagination: {
          page,
          limit,
          total,
          totalPages: Math.ceil(total / limit),
        },
      };
    }),

  // Protected endpoint - requires authentication
  getById: protectedProcedure
    .input(getUserSchema)
    .query(async ({ input, ctx }) => {
      const user = await ctx.db.user.findUnique({
        where: { id: input.id },
      });

      if (!user) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: 'User not found',
        });
      }

      return user;
    }),

  create: protectedProcedure
    .input(createUserSchema)
    .mutation(async ({ input, ctx }) => {
      // Check if email already exists
      const existing = await ctx.db.user.findUnique({
        where: { email: input.email },
      });

      if (existing) {
        throw new TRPCError({
          code: 'CONFLICT',
          message: 'Email already exists',
        });
      }

      const user = await ctx.db.user.create({
        data: input,
      });

      return user;
    }),

  update: protectedProcedure
    .input(updateUserSchema)
    .mutation(async ({ input, ctx }) => {
      const { id, ...updateData } = input;

      try {
        const user = await ctx.db.user.update({
          where: { id },
          data: updateData,
        });

        return user;
      } catch (error) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: 'User not found',
        });
      }
    }),

  delete: protectedProcedure
    .input(getUserSchema)
    .mutation(async ({ input, ctx }) => {
      try {
        await ctx.db.user.delete({
          where: { id: input.id },
        });

        return { success: true };
      } catch (error) {
        throw new TRPCError({
          code: 'NOT_FOUND',
          message: 'User not found',
        });
      }
    }),
});

// Export type-safe router type
export type UserRouter = typeof userRouter;
```

Client usage with full type safety:

```typescript
// client/hooks/useUsers.ts
import { trpc } from '../utils/trpc';

export function useUsers(page = 1, limit = 20) {
  // Fully typed - autocomplete works!
  const { data, isLoading, error } = trpc.user.list.useQuery({
    page,
    limit,
    // TypeScript knows valid values
    role: 'admin', // ✅ Valid
    // role: 'invalid', // ❌ Type error
  });

  return { users: data?.data, pagination: data?.pagination, isLoading, error };
}

export function useCreateUser() {
  const utils = trpc.useUtils();
  
  return trpc.user.create.useMutation({
    onSuccess: () => {
      // Invalidate and refetch users list
      utils.user.list.invalidate();
    },
  });
}
```

## REST API Best Practices

HTTP method semantics:

```typescript
// GET - Retrieve resources (idempotent, cacheable)
GET /api/v1/users          // List users
GET /api/v1/users/:id      // Get specific user

// POST - Create new resources (not idempotent)
POST /api/v1/users         // Create user
POST /api/v1/users/:id/verify  // Trigger action

// PUT - Replace entire resource (idempotent)
PUT /api/v1/users/:id      // Replace user (all fields required)

// PATCH - Partial update (not necessarily idempotent)
PATCH /api/v1/users/:id    // Update user (partial fields)

// DELETE - Remove resource (idempotent)
DELETE /api/v1/users/:id   // Delete user
```

HTTP status codes:

```typescript
// Success codes
200 OK                  // Successful GET, PATCH, or action
201 Created             // Successful POST with resource creation
204 No Content          // Successful DELETE or PUT with no response body

// Client error codes
400 Bad Request         // Invalid request syntax or validation failure
401 Unauthorized        // Missing or invalid authentication
403 Forbidden           // Authenticated but lacks permission
404 Not Found           // Resource doesn't exist
409 Conflict            // Resource conflict (duplicate email, etc.)
422 Unprocessable Entity // Valid syntax but semantic errors
429 Too Many Requests   // Rate limit exceeded

// Server error codes
500 Internal Server Error // Unexpected server error
502 Bad Gateway          // Upstream service error
503 Service Unavailable  // Temporary unavailability (maintenance)
504 Gateway Timeout      // Upstream timeout
```

Response envelope pattern:

```typescript
// ✅ Good - Consistent envelope
interface ApiResponse<T> {
  data: T;
  meta?: {
    timestamp: string;
    requestId: string;
  };
}

interface ApiError {
  error: {
    code: string;
    message: string;
    details?: Record<string, unknown>;
  };
  meta: {
    timestamp: string;
    requestId: string;
  };
}

// Success response
{
  "data": {
    "id": "user_123",
    "email": "alice@example.com"
  },
  "meta": {
    "timestamp": "2025-10-25T10:30:00Z",
    "requestId": "req_abc123"
  }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "not-an-email"
    }
  },
  "meta": {
    "timestamp": "2025-10-25T10:30:00Z",
    "requestId": "req_abc123"
  }
}
```

## GraphQL Schema Design

Type-safe GraphQL SDL:

```graphql
# schema.graphql
type User {
  id: ID!
  email: String!
  name: String!
  role: UserRole!
  createdAt: DateTime!
  updatedAt: DateTime!
  posts: [Post!]!
}

enum UserRole {
  ADMIN
  USER
  GUEST
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  publishedAt: DateTime
}

type Query {
  user(id: ID!): User
  users(
    page: Int = 1
    limit: Int = 20
    role: UserRole
  ): UserConnection!
  me: User
}

type Mutation {
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

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

input UpdateUserInput {
  name: String
  role: UserRole
}

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

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

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

scalar DateTime
```

## API Security Patterns

Authentication middleware:

```typescript
// middleware/auth.ts
import { TRPCError } from '@trpc/server';
import { verifyJWT } from '../utils/jwt';

export const authMiddleware = async ({ ctx, next }) => {
  const token = ctx.req.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
      message: 'Authentication required',
    });
  }

  try {
    const payload = await verifyJWT(token);
    
    // Attach user to context
    return next({
      ctx: {
        ...ctx,
        user: payload,
      },
    });
  } catch (error) {
    throw new TRPCError({
      code: 'UNAUTHORIZED',
      message: 'Invalid or expired token',
    });
  }
};
```

Rate limiting:

```typescript
// middleware/rateLimit.ts
import { Redis } from 'ioredis';
import { TRPCError } from '@trpc/server';

const redis = new Redis();

export const rateLimitMiddleware = (limit = 1000, window = 3600) => {
  return async ({ ctx, next }) => {
    const key = `ratelimit:${ctx.user?.id || ctx.ip}`;
    const current = await redis.incr(key);

    if (current === 1) {
      // First request - set expiry
      await redis.expire(key, window);
    }

    if (current > limit) {
      throw new TRPCError({
        code: 'TOO_MANY_REQUESTS',
        message: `Rate limit exceeded. Try again in ${window} seconds.`,
      });
    }

    // Add rate limit headers
    ctx.res.setHeader('X-RateLimit-Limit', limit);
    ctx.res.setHeader('X-RateLimit-Remaining', Math.max(0, limit - current));
    ctx.res.setHeader('X-RateLimit-Reset', Date.now() + window * 1000);

    return next();
  };
};
```

## Code Generation from Schemas

OpenAPI to TypeScript:

```bash
# Install openapi-typescript
pnpm add -D openapi-typescript

# Generate types
pnpm openapi-typescript ./openapi.yaml -o ./src/types/api.ts
```

Generated types usage:

```typescript
import type { paths } from './types/api';

// Extract request/response types
type ListUsersResponse = paths['/users']['get']['responses']['200']['content']['application/json'];
type CreateUserRequest = paths['/users']['post']['requestBody']['content']['application/json'];

// Fully typed API client
const users: ListUsersResponse = await fetch('/api/v1/users').then(r => r.json());
```

Always define API contracts before implementation, use Zod for runtime validation with tRPC, follow REST semantics strictly for HTTP APIs, implement comprehensive error handling with proper status codes, and generate TypeScript types from schemas for end-to-end type safety.