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.
  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.