# API Design Patterns

> RESTful API design patterns including URL structure, HTTP methods, and idempotency. Use when designing new API endpoints or reviewing API architecture. For existing projects, follow the project's established conventions instead.

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

---


# API Design Patterns

## Core Principle

For new projects, enforce RESTful URL structure. For existing projects, follow the project's established API conventions.

## RESTful URL Structure

```
GET    /api/resources              # List resources
GET    /api/resources/:id          # Get single resource
POST   /api/resources              # Create (server assigns ID)
PUT    /api/resources/:id          # Create or replace at specific ID
PATCH  /api/resources/:id          # Partial update
DELETE /api/resources/:id          # Delete resource

# Query parameters for filtering, sorting, pagination
GET /api/resources?status=active&sort=created_at&limit=20&offset=0
```

## HTTP Methods and Idempotency

| Method | Idempotent | Use Case |
|--------|------------|----------|
| GET | Yes | Retrieve resource(s) |
| PUT | Yes | Create or replace at specific URI |
| PATCH | No* | Partial update |
| DELETE | Yes | Remove resource |
| POST | No | Non-idempotent operations |

### PUT vs POST

**Common misconception**: "POST = create, PUT = update"
**Reality**: PUT can create, POST can do various things. The difference is idempotency.

- **PUT**: Client specifies the ID. Idempotent (running twice = same result)
- **POST**: Server assigns the ID. Non-idempotent (running twice = two resources)

## Anti-Patterns

| Anti-Pattern | Correct Approach |
|-------------|-----------------|
| Verbs in URLs (`/getUser/123`) | Use HTTP methods (`GET /users/123`) |
| Ignoring idempotency | PUT for idempotent creates, POST for non-idempotent |
| Inconsistent pluralization | Always use plural nouns (`/users`, not `/user`) |
| Deeply nested resources (`/a/1/b/2/c/3`) | Flatten beyond 2 levels |