320-api-design

API Design Best Practices

Audience: engineers designing and reviewing REST, GraphQL, and gRPC APIs Goal: Create consistent, secure, well-documented APIs that provide excellent developer experience

[!NOTE] This rule covers the API surface (verbs, status codes, versioning, authn/authz, schemas). For the transport and wire format layer beneath it - TCP keepalive, HoL blocking, TTFB budget, HTTP/1.1 vs 2 vs 3, gRPC/Protobuf vs REST/JSON decision matrix, connection pooling, long-lived connections - see 325-networking.mdc (file-scoped non-negotiables) and skills/networking-transport/ (the depth). The two layers compose; both are required for production API decisions.

API Design Philosophy (Core Principles)

Core Principles:

• "Consistency is king" - Follow conventions consistently across all endpoints
• "Developer experience matters" - APIs should be intuitive, well-documented, and easy to use
• "Versioning from day one" - Plan for evolution, maintain backward compatibility
• "Security by default" - Authentication, authorization, rate limiting, input validation
• "Documentation is part of the API" - Clear, accurate, up-to-date docs are essential
• "Fail fast, fail clearly" - Return meaningful error messages with actionable information
• "Performance matters" - Use pagination, caching, compression where appropriate
• "Idempotency where possible" - Make operations safe to retry

Applying API Design Principles:

// BAD: Inconsistent, insecure, undocumented
app.get('/getUsers', (req, res) => {
  const users = db.getUsers();
  res.json(users);
});

// GOOD: Consistent, secure, documented
/**
 * GET /api/v1/users
 * List users with pagination
 *
 * @query limit - Number of results (default: 20, max: 100)
 * @query offset - Pagination offset (default: 0)
 * @returns {User[]} Array of users
 */
app.get('/api/v1/users', authenticate, authorize('read:users'), async (req, res) => {
  const { limit = 20, offset = 0 } = req.query;

  // Validate input
  const validatedLimit = Math.min(parseInt(limit) || 20, 100);
  const validatedOffset = Math.max(parseInt(offset) || 0, 0);

  const users = await userService.listUsers({
    limit: validatedLimit,
    offset: validatedOffset,
  });

  res.json({
    data: users,
    pagination: {
      limit: validatedLimit,
      offset: validatedOffset,
      total: await userService.countUsers(),
    },
  });
});