# API Design

> RESTful API conventions

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

---


# API Design Standards

Consistent, intuitive interfaces.

## Endpoint Naming

- Resource-based: /users, /orders
- Plural nouns
- Nest for relationships: /users/:id/orders

## HTTP Methods

| Method | Purpose |
|--------|---------|
| GET | Retrieve |
| POST | Create |
| PUT | Replace |
| PATCH | Update |
| DELETE | Remove |

## Response Format

```json
{
  "success": boolean,
  "data": object | null,
  "error": string | null,
  "meta": { total, page, limit }
}
```

## Status Codes

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

## Security

- Auth on all endpoints
- Rate limiting
- Input validation
- No secrets in responses