# API Design

> This skill should be used for REST API, GraphQL, versioning, pagination, authentication, backend routes, web services, HTTP endpoints, server API design Use when this capability is needed.

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

---


# API Design

REST API design best practices.

## URL Structure

```
GET    /users          # List
GET    /users/:id      # Get one
POST   /users          # Create
PUT    /users/:id      # Replace
PATCH  /users/:id      # Update
DELETE /users/:id      # Delete
```

## Versioning

```
/api/v1/users          # URL versioning
Accept: application/vnd.api.v1+json  # Header
```

## Pagination

```json
{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "total_pages": 5
  }
}
```

## Error Responses

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [{"field": "email", "issue": "invalid format"}]
  }
}
```

## Status Codes

| Code | Use |
|------|-----|
| 200 | Success |
| 201 | Created |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Not found |
| 500 | Server error |

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/zate) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->