Skip to main content
skill CX Codex

api-contract-normalizer — Claude Code skill

The api-contract-normalizer skill aligns API responses across endpoints, covering envelopes, errors, pagination, status codes, and versioning. Use it when API conventions have drifted.

MIT 260 installs ★ 64 updated 2026-01-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add patricio0312rev/skills --skill api-contract-normalizer -a claude-code
Open on GitHub

What api-contract-normalizer does

api-contract-normalizer gives an agent a workflow for reviewing existing endpoints, defining shared response rules, and planning a move to the new contract. The proposed shape uses success, data, error, and meta, with TypeScript interfaces for regular and paginated responses.

Its material covers page-based and cursor-based pagination, an error taxonomy mapped to HTTP status codes, and version selection through URL paths or headers. It also includes middleware examples for wrapping successful responses and formatting errors, plus OpenAPI contract documentation. The middleware example is built around Express request and response types.

The migration section describes a staged change from the current format to the new one, including dual-format support and a later removal of the old shape. Examples use v1, v2, ?format=v2, request IDs, and response metadata.

What it helps with

  • standardize response envelopes across API endpoints
  • define shared page and cursor pagination metadata
  • map application errors to HTTP status codes
  • generate TypeScript interfaces for API contracts
  • plan a staged migration between response formats

Example prompts for the agent

  • Audit our endpoints and propose one response contract for the API.
  • Create TypeScript interfaces, Express middleware, and OpenAPI documentation for the shared format.
  • Plan a migration to v2 while keeping the old response format available during the transition.

How to install api-contract-normalizer

1Skills CLI (Vercel)

npx skills add patricio0312rev/skills --skill api-contract-normalizer -a claude-code

2Manually: put the files in place

~/.claude/skills/api-endpoint-generator/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-endpoint-generator/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-contract-normalizer

How do I install api-contract-normalizer in Claude Code?

Run npx skills add patricio0312rev/skills --skill api-endpoint-generator -a claude-code, then check ~/.claude/skills/api-endpoint-generator/SKILL.md.

What does api-contract-normalizer do?

It helps unify API envelopes, error shapes, pagination rules, status codes, and versioning. The workflow also covers shared TypeScript types, response middleware, contract docs, and migration steps.

What does the response middleware rely on?

The example targets Express and wraps res.json. It adds metadata to successful responses and turns errors into a structured payload with a request ID and API version.

Source text

SKILL.md · MIT
---
name: api-contract-normalizer
description: Unifies API response patterns across endpoints including pagination format, error structure, status codes, response envelopes, and versioning strategy. Provides contract documentation, shared TypeScript types, middleware utilities, and migration plan. Use when standardizing "API contracts", "response formats", "API conventions", or "API consistency".
---

# API Contract Normalizer

Standardize API contracts across all endpoints for consistency and developer experience.

## Core Workflow

1. **Audit existing APIs**: Document current inconsistencies
2. **Define standards**: Response format, pagination, errors, status codes
3. **Create shared types**: TypeScript interfaces for all contracts
4. **Build middleware**: Normalize responses automatically
5. **Document contract**: OpenAPI spec with examples
6. **Migration plan**: Phased rollout strategy
7. **Versioning**: API version strategy

## Standard Response Envelope

```typescript
// types/api-contract.ts
export interface ApiResponse<T = unknown> {
  success: boolean;
  data?: T;
  error?: ApiError;
  meta?: ResponseMeta;
}

export interface ApiError {
  code: string;
  message: string;
  details?: Record<string, string[] | string>;
  trace_id?: string;
}

export interface ResponseMeta {
  timestamp: string;
  request_id: string;
  version: string;
}

export interface PaginatedResponse<T> extends ApiResponse<T[]> {
  meta: ResponseMeta & PaginationMeta;
}

export interface PaginationMeta {
  page: number;
  limit: number;
  total: number;
  total_pages: number;
  has_next: boolean;
  has_prev: boolean;
}
```

## Pagination Standards

```typescript
// Standard pagination query params
interface PaginationQuery {
  page: number;      // 1-indexed, default: 1
  limit: number;     // default: 10, max: 100
  sort_by?: string;  // field name
  sort_order?: 'asc' | 'desc'; // default: 'desc'
}

// Standard pagination response
{
  "success": true,
  "data": [...],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 156,
    "total_pages": 16,
    "has_next": true,
    "has_prev": false
  }
}

// Cursor-based pagination (for large datasets)
interface CursorPaginationQuery {
  cursor?: string;
  limit: number;
}

interface CursorPaginationMeta {
  next_cursor?: string;
  prev_cursor?: string;
  has_more: boolean;
}
```

## Error Standards

```typescript
// Error taxonomy
export enum ErrorCode {
  // Client errors (4xx)
  VALIDATION_ERROR = 'VALIDATION_ERROR',
  UNAUTHORIZED = 'UNAUTHORIZED',
  FORBIDDEN = 'FORBIDDEN',
  NOT_FOUND = 'NOT_FOUND',
  CONFLICT = 'CONFLICT',
  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',

  // Server errors (5xx)
  INTERNAL_ERROR = 'INTERNAL_ERROR',
  SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE',
  TIMEOUT = 'TIMEOUT',
}

// Error to HTTP status mapping
export const ERROR_STATUS_MAP: Record<ErrorCode, number> = {
  VALIDATION_ERROR: 400,
  UNAUTHORIZED: 401,
  FORBIDDEN: 403,
  NOT_FOUND: 404,
  CONFLICT: 409,
  RATE_LIMIT_EXCEEDED: 429,
  INTERNAL_ERROR: 500,
  SERVICE_UNAVAILABLE: 503,
  TIMEOUT: 504,
};

// Standard error responses
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": {
      "email": ["Invalid email format"],
      "age": ["Must be at least 18"]
    },
    "trace_id": "abc123"
  }
}
```

## Response Normalization Middleware

```typescript
// middleware/normalize-response.ts
import { Request, Response, NextFunction } from "express";

export function normalizeResponse() {
  return (req: Request, res: Response, next: NextFunction) => {
    const originalJson = res.json.bind(res);

    res.json = function (data: any) {
      // Already normalized
      if (data.success !== undefined) {
        return originalJson(data);
      }

      // Normalize success response
      const normalized: ApiResponse = {
        success: true,
        data,
        meta: {
          timestamp: new Date().toISOString(),
          request_id: req.id,
          version: "v1",
        },
      };

      return originalJson(normalized);
    };

    next();
  };
}

// Error normalization middleware
export function normalizeError() {
  return (err: Error, req: Request, res: Response, next: NextFunction) => {
    const error: ApiError = {
      code: err.name || "INTERNAL_ERROR",
      message: err.message || "An unexpected error occurred",
      trace_id: req.id,
    };

    if (err instanceof ValidationError) {
      error.details = err.details;
    }

    const statusCode = ERROR_STATUS_MAP[error.code] || 500;

    res.status(statusCode).json({
      success: false,
      error,
      meta: {
        timestamp: new Date().toISOString(),
        request_id: req.id,
        version: "v1",
      },
    });
  };
}
```

## Status Code Standards

```typescript
// Standard status codes by operation
const STATUS_CODES = {
  // Success
  OK: 200, // GET, PUT, PATCH success
  CREATED: 201, // POST success
  NO_CONTENT: 204, // DELETE success

  // Client errors
  BAD_REQUEST: 400, // Validation errors
  UNAUTHORIZED: 401, // Missing/invalid auth
  FORBIDDEN: 403, // Insufficient permissions
  NOT_FOUND: 404, // Resource not found
  CONFLICT: 409, // Duplicate/conflict
  UNPROCESSABLE: 422, // Semantic errors
  TOO_MANY_REQUESTS: 429, // Rate limit

  // Server errors
  INTERNAL_ERROR: 500, // Unexpected errors
  SERVICE_UNAVAILABLE: 503, // Temporarily down
  GATEWAY_TIMEOUT: 504, // Upstream timeout
};
```

## Versioning Strategy

```typescript
// URL versioning (recommended)
/api/v1/users
/api/v2/users

// Header versioning
Accept: application/vnd.api.v1+json

// Query param versioning (not recommended)
/api/users?version=1

// Version middleware
export function apiVersion(version: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    req.apiVersion = version;
    res.setHeader('X-API-Version', version);
    next();
  };
}

// Route versioning
app.use('/api/v1', apiVersion('v1'), v1Router);
app.use('/api/v2', apiVersion('v2'), v2Router);
```

## Migration Strategy

```markdown
# API Contract Migration Plan

## Phase 1: Add Normalization (Week 1-2)

- [ ] Deploy normalization middleware
- [ ] Run alongside existing responses
- [ ] Monitor for issues
- [ ] No breaking changes yet

## Phase 2: Deprecation Notice (Week 3-4)

- [ ] Add deprecation headers
- [ ] Update documentation
- [ ] Notify API consumers
- [ ] Provide migration guide

## Phase 3: Dual Format Support (Week 5-8)

- [ ] Support both old and new formats
- [ ] Add ?format=v2 query param
- [ ] Track adoption metrics
- [ ] Help consumers migrate

## Phase 4: Switch Default (Week 9-10)

- [ ] New format becomes default
- [ ] Old format requires ?format=v1
- [ ] Final migration reminders
- [ ] Extended support period

## Phase 5: Remove Old Format (Week 12+)

- [ ] Remove old format support
- [ ] Clean up legacy code
- [ ] Update all documentation
- [ ] Celebrate consistency! 🎉
```

## Contract Documentation

```yaml
# openapi.yaml
openapi: 3.0.0
info:
  title: Standardized API
  version: 1.0.0
  description: All endpoints follow this contract

components:
  schemas:
    ApiResponse:
      type: object
      required: [success]
      properties:
        success:
          type: boolean
        data:
          type: object
        error:
          $ref: "#/components/schemas/ApiError"
        meta:
          $ref: "#/components/schemas/ResponseMeta"

    ApiError:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          enum: [VALIDATION_ERROR, UNAUTHORIZED, ...]
        message:
          type: string
        details:
          type: object
          additionalProperties: true
        trace_id:
          type: string

    PaginationMeta:
      type: object
      required: [page, limit, total, total_pages]
      properties:
        page: { type: integer }
        limit: { type: integer }
        total: { type: integer }
        total_pages: { type: integer }
        has_next: { type: boolean }
        has_prev: { type: boolean }
```

## Shared Utilities

```typescript
// utils/api-response.ts
export class ApiResponseBuilder {
  static success<T>(data: T, meta?: Partial<ResponseMeta>): ApiResponse<T> {
    return {
      success: true,
      data,
      meta: {
        timestamp: new Date().toISOString(),
        ...meta,
      },
    };
  }

  static paginated<T>(
    data: T[],
    pagination: PaginationMeta
  ): PaginatedResponse<T> {
    return {
      success: true,
      data,
      meta: {
        timestamp: new Date().toISOString(),
        ...pagination,
      },
    };
  }

  static error(code: ErrorCode, message: string, details?: any): ApiResponse {
    return {
      success: false,
      error: { code, message, details },
      meta: {
        timestamp: new Date().toISOString(),
      },
    };
  }
}
```

## Best Practices

1. **Consistent envelope**: All responses use same structure
2. **Type safety**: Shared types across frontend/backend
3. **Clear errors**: Descriptive codes and messages
4. **Standard pagination**: Same format for all lists
5. **Versioning**: Plan for API evolution
6. **Documentation**: OpenAPI spec as source of truth
7. **Gradual migration**: Don't break existing clients
8. **Monitoring**: Track adoption and errors

## Output Checklist

- [ ] Standard response envelope defined
- [ ] Error taxonomy documented
- [ ] Pagination format standardized
- [ ] Status code mapping
- [ ] Normalization middleware
- [ ] Shared TypeScript types
- [ ] Versioning strategy
- [ ] OpenAPI specification
- [ ] Migration plan with phases
- [ ] Consumer communication plan

© patricio0312rev · MIT · patricio0312rev/skills

Similar skills

All skills for Backend and APIs →

From the same set148

The whole set →
kubernetes-manifest-generator kubernetes-manifest-generator produces production-grade Kubernetes YAML manifests with hardening, autoscaling, and networking defaults. Useful when preparing workloads for cluster deployment. CX Codex +1 262installs caching-cdn-strategy-planner caching-cdn-strategy-planner is a Claude Code skill for planning CDN and server-side caching, response headers, and invalidation. Use it in API design. CX Codex +1 262installs dependency-doctor dependency-doctor scans your manifests, flags outdated and duplicated packages, known CVEs and risky version pairs, then hands back a report with a step-by-step upgrade plan. CX Codex +1 261installs db-performance-watchlist db-performance-watchlist is a Claude Code skill that tracks PostgreSQL metrics, including slow queries, connection pools, and unused indexes through Prisma. CX Codex +1 260installs vscode-rest-client-generator vscode-rest-client-generator generates .http files from Express, Next.js, and Fastify routes for the VS Code REST Client extension. Ideal for testing APIs in the editor without Postman. CX Codex +1 259installs embedding-pipeline-builder embedding-pipeline-builder builds document embedding workflows for loading, cleaning, chunking, indexing, and retrieval. Useful when setting up RAG preprocessing or semantic search. CX Codex +1 259installs llm-debugger llm-debugger diagnoses LLM output failures, patches faulty prompts, refines tool schemas, and generates regression test cases. CX Codex +1 259installs tool-function-schema-designer tool-function-schema-designer turns a rough tool idea into a JSON schema, a typed interface, a validation layer and example calls the model can actually follow. CX Codex +1 258installs

Project sponsors

Companies that keep this analytics open