# Design API Design

> Design API endpoints: routes, request/response shapes, authentication, pagination, error responses, and versioning strategy.

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

---


!`bash ~/.claude/hooks/sweetclaude/record-event.sh skill_invoked "sweetclaude:design-api-design" 2>/dev/null || true`

!`cat .sweetclaude/state/session-state.yaml 2>/dev/null || echo "STATE_NOT_FOUND"`

<preflight-guard>
STOP. Before executing this skill, check: does .sweetclaude/state/phase.yaml exist in the project directory? If NO, do not proceed. Tell the user: "This project is not set up for SweetClaude. Running the pre-flight check now." Then invoke the sweetclaude master skill (Skill tool, skill: "sweetclaude:master") and run its pre-flight. Return here only after the pre-flight passes.
</preflight-guard>

# API Design

## Artifact Path Resolution

Before writing any artifact file:

1. Read `.sweetclaude/artifact-privacy.yaml`. If it does not exist, stop and say:
   > "No artifact privacy manifest found. Run `/sweetclaude:setup` to configure artifact privacy, then return here."
   Do not guess a path. Do not fall back to a default.

2. Read `categories.technical.base_path`. This is the base directory for all technical artifacts.

3. Construct full paths as `{base_path}/{filename}`, e.g. `{base_path}/architecture.md`, `{base_path}/tech-spec-v1.md`.

4. Write artifacts to those paths.

Design the API for: $ARGUMENTS

## Context

Read architecture doc, data model, and user stories from `docs/` and `.sweetclaude/stories/`.

## Process

### 1. Endpoint inventory

List every endpoint needed. For each:
- HTTP method and path
- Purpose (one sentence)
- Who can call it (auth requirements)

### 2. Detailed design per endpoint

For each endpoint:

```
### {METHOD} {path}

**Purpose:** {what it does}
**Auth:** {required role/permission}

Request:
  Headers: {required headers}
  Params: {path and query params with types}
  Body: {JSON shape with types}

Response 200:
  {JSON shape with types}

Response 4xx:
  {error shapes — 400 validation, 401 unauth, 403 forbidden, 404 not found}

Response 5xx:
  {generic error shape}
```

### 3. Cross-cutting concerns

- **Pagination:** pattern (cursor vs offset), defaults, maximums
- **Filtering/sorting:** query param conventions
- **Versioning:** strategy (URL path, header, none)
- **Rate limiting:** if applicable
- **CORS:** allowed origins

### 4. Save

Save to `{base_path}/api-design.md`. Record key decisions via `design/manage-decisions`.