# backend-api-design

Tells the agent how to shape RPC-style APIs: a thin controller, a manager holding business logic, a repository for data access. Useful when adding endpoints or auditing existing ones.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · ★ 109
- Author: c0x12c
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/c0x12c/ai-toolkit/tree/HEAD/toolkit/skills/backend-api-design/SKILL.md
- Updated: 2026-06-18
- HTML: https://affpapa.org/en/nevibecode/skills/backend-api-design

## What it does

The skill lays out URL rules that leave little room for interpretation. Path parameters are out — query values only. A single resource stays singular (`/employee`), a collection goes plural (`/employees`), and actions live in sub-paths such as `/delete`, `/restore` or `/sync`. Every mutation is a `@Post`; `@Put`, `@Delete` and `@Patch` are off the table.

Each layer gets its own job. The controller parses query params with defaults, hands off to the manager, then unwraps the result with `.throwOrValue()`. The manager returns `Either<ClientException, T>`, wraps database work in `transaction(db.primary) { }` and enforces business rules. The repository reads from `db.replica`, writes to `db.primary` and filters out soft-deleted rows with `deletedAt.isNull()`.

A gotchas section covers the traps. Multi-word `@QueryValue` params need an explicit snake_case name — write `@QueryValue("project_id") projectId: UUID`, because Micronaut matches the literal name while the frontend sends `project_id`. A second `.where {}` call silently replaces the first condition, so chain with `.andWhere {}` instead. And skip `@ExecuteOn(TaskExecutors.IO)` at your peril: without it suspend functions may hang or land on the wrong thread pool, so every controller needs the annotation.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/backend-api-design/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/backend-api-design/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/backend-api-design/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/backend-api-design/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install c0x12c/ai-toolkit backend-api-design
```

2. **Manually: put the files in place**
- File: `.github/skills/backend-api-design/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/c0x12c/ai-toolkit --path toolkit/skills/backend-api-design
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/backend-api-design/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add c0x12c/ai-toolkit --skill backend-api-design -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/c0x12c/ai-toolkit/tree/HEAD/toolkit/skills/backend-api-design/SKILL.md

## When to use it
- design a new endpoint contract without path parameters
- split business logic across controller, manager and repository
- move transactions and error returns out of the controller
- spot a repository injected straight into a controller
- build a paginated response with items, total, page, limit and hasMore

## Example prompts
- Design the employee endpoints following the skill rules: list, create, delete, restore
- Review this controller and tell me where it breaks the layered architecture
- Add offset pagination to the employee list and return it as EmployeeListResponse

## Similar
- [api-design-principles](https://affpapa.org/en/nevibecode/skills/sickn33-api-design-principles.md) — skill · 1000 installs
- [api-design-patterns](https://affpapa.org/en/nevibecode/skills/bobmatnyc-api-design-patterns.md) — skill · 566 installs
- [alchemy-api](https://affpapa.org/en/nevibecode/skills/alchemy-api.md) — skill · 1600 installs
- [backend-architect](https://affpapa.org/en/nevibecode/agents/backend-architect.md) — subagent · 23691 installs
- [rest-api-design](https://affpapa.org/en/nevibecode/skills/secondsky-rest-api-design.md) — skill · 586 installs
- [kotlin-api-design](https://affpapa.org/en/nevibecode/skills/kotlin-api-design.md) — skill · 949 installs

From the same set: [c0x12c/ai-toolkit](https://affpapa.org/en/nevibecode/by/c0x12c/ai-toolkit.md) — 11 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md