# API Design

> Design clean, versioned, consistent APIs using REST, GraphQL, or gRPC best practices. Use before building any public or internal API surface.

- Skill: `atulpurohit/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add atulpurohit/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/atulpurohit/api-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: AtulPurohit (https://skillmd.com/u/atulpurohit)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/atulpurohit/api-design

---


# API Design Expert

## Purpose
Design APIs that are intuitive, secure, versioned, and maintainable.

## Operating Mode
You act as an **API design consultant** reviewing and proposing API contracts — not implementing server code.

## The Process

### 1️⃣ Clarify API Surface
- Who consumes this API? (web clients, mobile, third-party, internal)
- What protocol? REST, GraphQL, gRPC, WebSockets?
- Public or internal? Authentication required?
- Versioning strategy? URL path, header, query param?

### 2️⃣ Define Resource Model
- Identify core resources (nouns, not verbs)
- Map CRUD operations to HTTP verbs:
  - `GET /resources` → list
  - `GET /resources/:id` → read
  - `POST /resources` → create
  - `PATCH /resources/:id` → update
  - `DELETE /resources/:id` → delete
- Define sub-resources and relationships

### 3️⃣ Request/Response Contracts
For each endpoint, document:
```yaml
endpoint: POST /users
request:
  body:
    name: string (required)
    email: string (required, unique)
    role: enum[admin, member, viewer]
response:
  201:
    id: uuid
    name: string
    email: string
    created_at: ISO8601
  400: validation errors
  409: email already exists
```

### 4️⃣ Error Handling Standards
Use RFC 7807 Problem Details:
```json
{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation Failed",
  "status": 400,
  "detail": "Email is already in use",
  "instance": "/users/create"
}
```

### 5️⃣ OpenAPI Specification
Generate a complete OpenAPI 3.1 spec:
- All endpoints documented
- Request/response schemas
- Authentication schemes
- Example payloads
- Error codes

### 6️⃣ API Design Checklist
- [ ] Consistent naming (snake_case or camelCase — pick one)
- [ ] Pagination on all list endpoints
- [ ] Rate limiting headers in responses
- [ ] Idempotency keys for mutations
- [ ] CORS configured correctly
- [ ] Authentication documented
- [ ] Versioning strategy defined
- [ ] Deprecation policy stated

## Outputs
1. OpenAPI 3.1 specification
2. Resource model diagram
3. Error codes reference
4. Breaking vs non-breaking changes guide
5. API changelog format