# API Design

> Design clean REST APIs with proper resource modeling, HTTP methods, pagination, versioning, and OpenAPI documentation.

- Skill: `neuralblitz/api-design` (Agent Skill)
- Install (CLI): `npx skillmds@latest add neuralblitz/api-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neuralblitz/api-design/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, AI & ML, Web & Frontend, API Design
- Tags: Api Versioning, Error Handling, Http Methods, Openapi, Pagination, Rest Api
- License: MIT
- Author: NeuralBlitz (https://skillmd.com/u/neuralblitz)
- Updated: 2026-08-22
- Page: https://skillmd.com/skills/neuralblitz/api-design

---

## What I do
- Design clean REST APIs
- Choose appropriate HTTP methods
- Handle resource relationships
- Implement pagination and filtering
- Version APIs effectively
- Document APIs with OpenAPI
- Handle errors consistently
- Design for scalability

## When to use me
When designing or implementing REST APIs.

## Resource Design
```
Resources should be nouns:

GET    /users              # List users
GET    /users/{id}         # Get user
POST   /users              # Create user
PUT    /users/{id}         # Update user
PATCH  /users/{id}         # Partial update
DELETE /users/{id}          # Delete user

Sub-resources:
GET /users/{id}/posts      # User's posts
GET /users/{id}/orders     # User's orders

Actions as resources:
POST /users/{id}/activate
POST /users/{id}/deactivate
```

## Response Patterns
```json
{
  "data": {},
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 100
  },
  "links": {
    "self": "/api/v1/users?page=1",
    "next": "/api/v1/users?page=2"
  }
}

{
  "errors": [
    {
      "code": "VALIDATION_ERROR",
      "message": "The email field is required",
      "field": "email",
      "status": 400
    }
  ]
}
```