API Dev

API Development

This skill provides structured guidance for designing and building robust REST and GraphQL APIs, with patterns for schema design, versioning, authentication, rate limiting, and documentation.

Prerequisites

• A backend framework (Express, Fastify, Django, FastAPI, etc.)
• Understanding of HTTP fundamentals
• Database access for persistence

When to Use This Skill

• Designing a new REST or GraphQL API
• Implementing authentication and authorization
• Adding rate limiting and request throttling
• Versioning an existing API
• Creating API documentation (OpenAPI/GraphQL schema)
• Structuring error responses consistently

REST API Design

Schema-First Design Process

1. Define resources — What entities does your API expose?
2. Define relationships — How do resources relate to each other?
3. Define operations — What can clients do with each resource?
4. Define representations — What does each resource look like in JSON?
5. Define status codes — What HTTP status for each outcome?

URL Structure

# ✅ Resource-based URLs (nouns, not verbs)
GET    /api/v1/users          # List users
POST   /api/v1/users          # Create user
GET    /api/v1/users/:id      # Get user
PATCH  /api/v1/users/:id      # Update user
DELETE /api/v1/users/:id      # Delete user

# ✅ Nested resources (limit to 1 level of nesting)
GET    /api/v1/users/:id/posts       # User's posts
POST   /api/v1/users/:id/posts       # Create post for user

# ✅ Actions as sub-resources (when not CRUD)
POST   /api/v1/users/:id/activate    # Activate user
POST   /api/v1/orders/:id/cancel     # Cancel order

# ❌ Avoid verb-based URLs
GET    /api/v1/getUsers
POST   /api/v1/createUser
POST   /api/v1/deleteUser/123

Response Format

// ✅ Consistent envelope
{
  "data": {
    "id": "usr_abc123",
    "name": "Jane Doe",
    "email": "jane@example.com"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}

// ✅ Collection with pagination
{
  "data": [
    { "id": "usr_abc123", "name": "Jane Doe" }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 156,
    "total_pages": 8
  },
  "links": {
    "self": "/api/v1/users?page=1",
    "next": "/api/v1/users?page=2",
    "last": "/api/v1/users?page=8"
  }
}

// ✅ Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      {
        "field": "email",
        "message": "Must be a valid email address",
        "value": "not-an-email"
      }
    ],
    "request_id": "req_xyz789"
  }
}

HTTP Status Codes

Filtering, Sorting, Pagination

# Filtering (field=value, supports operators)
GET /api/v1/users?status=active&created_after=2025-01-01

# Sorting (field for asc, -field for desc)
GET /api/v1/users?sort=-created_at,name

# Pagination (cursor-based for large datasets)
GET /api/v1/users?cursor=abc123&limit=20

# Pagination (offset-based for small datasets)
GET /api/v1/users?page=2&per_page=20

# Field selection (sparse fieldsets)
GET /api/v1/users?fields=id,name,email

# Include related resources
GET /api/v1/users/:id?include=posts,profile

GraphQL API Design

Schema-First Approach

# Schema definition comes before implementation

type User {
  id: ID!
  name: String!
  email: String!
  role: Role!
  posts(limit: Int = 10): [Post!]!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  tags: [Tag!]!
  publishedAt: DateTime
}

enum Role {
  ADMIN
  EDITOR
  VIEWER
}

# Queries (read operations)
type Query {
  user(id: ID!): User
  users(
    filter: UserFilter
    sort: UserSort
    first: Int = 20
    after: String
  ): UserConnection!
  post(id: ID!): Post
}

# Mutations (write operations)
type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
  deleteUser(id: ID!): DeleteUserPayload!
}

# Subscriptions (real-time)
type Subscription {
  userUpdated(id: ID): User!
  postCreated(authorId: ID): Post!
}

# Input types (separate from output types)
input CreateUserInput {
  name: String!
  email: String!
  role: Role = VIEWER
}

# Payload types (for consistent mutation responses)
type CreateUserPayload {
  user: User
  errors: [FieldError!]
}

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

GraphQL Best Practices

• Separate input and output types — CreateUserInput ≠ User
• Use cursor-based pagination — first/after pattern with Connection types
• N+1 prevention — Use DataLoader for batched fetching
• Nullability — Mark fields ! only when they're guaranteed to exist
• Versioning — Evolve schema (add fields, never remove); avoid versioned endpoints
• Depth limiting — Cap query depth to prevent abuse (max 5-7 levels)
• Cost analysis — Assign complexity scores and limit per-query cost

Authentication

JWT Pattern

// Token structure
interface TokenPayload {
  sub: string;      // User ID
  iat: number;      // Issued at
  exp: number;      // Expiration
  role: string;     // Authorization role
  scope: string[];  // Permission scopes
}

// Middleware pattern
async function authMiddleware(req, res, next) {
  const token = extractBearerToken(req);
  if (!token) {
    return res.status(401).json({
      error: { code: 'UNAUTHORIZED', message: 'Missing authorization token' }
    });
  }

  try {
    const payload = verifyToken(token);
    req.user = payload;
    next();
  } catch (err) {
    if (err.name === 'TokenExpiredError') {
      return res.status(401).json({
        error: { code: 'TOKEN_EXPIRED', message: 'Token has expired' }
      });
    }
    return res.status(401).json({
      error: { code: 'INVALID_TOKEN', message: 'Token is invalid' }
    });
  }
}

// Role-based access
function requireRole(...roles: string[]) {
  return (req, res, next) => {
    if (!roles.includes(req.user.role)) {
      return res.status(403).json({
        error: { code: 'FORBIDDEN', message: 'Insufficient permissions' }
      });
    }
    next();
  };
}

API Key Pattern

// For service-to-service or third-party access
interface ApiKey {
  key: string;          // Hashed in storage
  prefix: string;       // First 8 chars for identification
  scopes: string[];     // Permitted operations
  rate_limit: number;   // Requests per minute
  expires_at: Date;
}

// Header: X-API-Key: ak_live_abc123def456

Rate Limiting

Implementation Strategies

// Sliding window rate limiter (Redis-backed)
async function rateLimiter(
  key: string,
  limit: number,
  windowMs: number
): Promise<{ allowed: boolean; remaining: number; resetAt: number }> {
  const now = Date.now();
  const windowKey = `ratelimit:${key}`;

  // Remove expired entries and add current request
  const pipeline = redis.pipeline();
  pipeline.zremrangebyscore(windowKey, 0, now - windowMs);
  pipeline.zadd(windowKey, now, `${now}-${Math.random()}`);
  pipeline.zcard(windowKey);
  pipeline.pexpire(windowKey, windowMs);

  const results = await pipeline.exec();
  const count = results[2][1] as number;

  return {
    allowed: count <= limit,
    remaining: Math.max(0, limit - count),
    resetAt: now + windowMs,
  };
}

Rate Limit Headers

X-RateLimit-Limit: 100          # Max requests per window
X-RateLimit-Remaining: 67       # Remaining in current window
X-RateLimit-Reset: 1704067200   # Unix timestamp when window resets
Retry-After: 30                 # Seconds to wait (only on 429)

Rate Limit Tiers

Versioning

Strategies Comparison

Recommendation: URL path versioning for REST, schema evolution for GraphQL.

Versioning Workflow

1. New version — Create new route prefix or endpoint
2. Deprecation notice — Add Sunset and Deprecation headers to old version
3. Migration period — Support both versions for 6+ months
4. Communication — Email, changelog, header notices
5. Sunset — Remove old version, return 410 Gone

Error Handling

Error Code System

// Structured error codes: DOMAIN_ENTITY_ERROR
const ErrorCodes = {
  // Auth errors (AUTH_*)
  AUTH_UNAUTHORIZED: 'Authentication required',
  AUTH_TOKEN_EXPIRED: 'Token has expired',
  AUTH_FORBIDDEN: 'Insufficient permissions',

  // Validation errors (VAL_*)
  VAL_INVALID_INPUT: 'Request validation failed',
  VAL_MISSING_FIELD: 'Required field is missing',
  VAL_INVALID_FORMAT: 'Field format is invalid',

  // Resource errors (RES_*)
  RES_NOT_FOUND: 'Resource not found',
  RES_CONFLICT: 'Resource already exists',
  RES_GONE: 'Resource has been removed',

  // Rate limit errors (RATE_*)
  RATE_LIMITED: 'Rate limit exceeded',
} as const;

class ApiError extends Error {
  constructor(
    public code: string,
    public status: number,
    message: string,
    public details?: unknown[]
  ) {
    super(message);
  }
}

Tips

• Use schema-first design for both REST and GraphQL — define the contract before implementing
• Return consistent error envelopes with machine-readable codes, not just messages
• Paginate all list endpoints; use cursor-based pagination for large datasets
• Version your REST API in the URL path; evolve your GraphQL schema instead of versioning
• Rate limit by default, even for authenticated users — abuse comes from all sources
• Document with OpenAPI (REST) or introspection + descriptions (GraphQL) — never keep docs separate from code
• Use Sunset headers when deprecating endpoints — give clients time to migrate
• Log request IDs for tracing — every error response should include the request ID

Cline Workflow Notes

1. Install location: Copy this skill directory to .cline/skills/api-dev/ (project-level) or ~/.cline/skills/api-dev/ (global)
2. Activation: Cline will automatically suggest this skill when you mention API design, REST endpoints, or GraphQL schemas
3. Progressive loading: Only the metadata loads initially; full instructions activate via use_skill when API work begins