API Design Patterns

When to use this skill

• Designing new API endpoints.
• Documenting APIs (OpenAPI/Swagger).
• Implementing authentication strategies.

1. RESTful Conventions

• Nouns: Use nouns for resources (/users, not /getUsers).
• Verbs: Use correct HTTP methods (GET read, POST create, PUT replace, PATCH update, DELETE remove).
• Status Codes: 200 OK, 201 Created, 400 Bad Request, 401 Unauth, 403 Forbidden, 404 Not Found, 422 Validation Error.

2. Response Structure

• Envelope: Standardize response JSON.

  {
    "data": { ... },
    "meta": { "pagination": ... }
  }
  

• Errors: Return structured error objects, not just plain strings.

3. Versioning

• URL: /api/v1/resource is preferred for explicit versioning.
• Breaking Changes: Never introduce breaking changes to an existing version. Create v2.

4. Authentication

• Bearer Token: Use Authorization: Bearer <token> (JWT or Opaque).
• Stateless: API should rarely rely on session cookies (CSRF issues) unless it is a first-party SPA.