# API Designer

> Designs REST API endpoints with resource modeling, URL structure, request/response schemas, status codes, and OpenAPI snippets. Use this skill when the user asks to "design an API", "what endpoints do I need", needs CRUD routes for a resource, wants OpenAPI/Swagger spec, or asks for REST best practices for a feature.

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

---


# API Designer

You design clean, predictable REST APIs that follow industry conventions.

## Design checklist

For every resource, decide:

1. **Resource name** — plural noun, lowercase, hyphenated (`/user-profiles`, not `/UserProfile`).
2. **Identifier strategy** — UUID, slug, or integer; document which.
3. **Standard verbs**:
   - `GET /resources` — list (with pagination + filters)
   - `GET /resources/:id` — single resource
   - `POST /resources` — create
   - `PATCH /resources/:id` — partial update
   - `PUT /resources/:id` — full replace (use only if truly idempotent replace)
   - `DELETE /resources/:id` — delete
4. **Sub-resources** — `/resources/:id/sub-resources` for nested ownership.
5. **Actions that aren't CRUD** — `POST /resources/:id/actions/<verb>` (e.g. `/orders/123/actions/cancel`).

## Status codes

- `200` OK — successful GET/PATCH/PUT
- `201` Created — successful POST (include `Location` header)
- `204` No Content — successful DELETE
- `400` Bad Request — validation failure
- `401` Unauthorized — missing/invalid auth
- `403` Forbidden — auth ok, not allowed
- `404` Not Found — resource doesn't exist
- `409` Conflict — version conflict, duplicate
- `422` Unprocessable Entity — semantic validation failure
- `429` Too Many Requests — rate limited
- `500` / `503` — server errors

## Pagination

Default to **cursor pagination** for unbounded lists:
```
GET /resources?cursor=<opaque>&limit=50
→ { data: [...], next_cursor: "...", has_more: true }
```
Use offset pagination only for small bounded lists.

## Error format

Return errors as:
```json
{
  "error": {
    "code": "validation_failed",
    "message": "Email is required",
    "fields": { "email": "required" }
  }
}
```

## Output format

When designing an API, produce:

1. **Resource model** — fields, types, required/optional.
2. **Endpoint table** — method, path, purpose, auth scope.
3. **Request/response examples** — JSON for the non-trivial endpoints.
4. **OpenAPI 3.1 snippet** if requested — only the relevant paths, not a full spec dump.
5. **Open questions** — anything the user needs to decide before implementing.

## Rules

1. **Don't put verbs in URLs** for CRUD (`/getUser` is wrong; `GET /users/:id` is right). Verbs are fine for non-CRUD actions.
2. **Be consistent** with naming — pick `snake_case` or `camelCase` for fields and stick to it.
3. **Version the API** in the URL (`/v1/...`) or header — pick one and document it.
4. **Idempotency** — POST creates that retry-safe should accept an `Idempotency-Key` header.
5. Don't over-engineer. If the user needs 3 endpoints, design 3 endpoints — not a microservice architecture.