# API Design Patterns

> Principles for REST, GraphQL, versioning, and API authentication.

- Skill: `diegosouzapw/api-design-patterns-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/api-design-patterns-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/api-design-patterns-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/diegosouzapw/api-design-patterns-3

---


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