# API Designer

API Designer guides REST and GraphQL design with consistent resource naming, standard error formats, and pagination patterns.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 204 installs · ★ 39 repo stars
- Author: daffy0208
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/daffy0208/ai-dev-standards/tree/HEAD/skills/api-designer/SKILL.md
- Updated: 2025-12-25
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/daffy0208-api-designer

## What it does

The skill sets concrete conventions for backend interfaces. It provides templates for standard JSON responses, structured errors with `request_id`, and explicit status code mappings across HTTP methods. Endpoints strictly use plural nouns instead of verbs.

For datasets that change frequently, cursor-based pagination is preferred over offset methods. Versioning defaults to explicit URL prefixes such as `/v1/`, paired with a requirement to maintain both the current and previous release simultaneously.

Security rules permit no exceptions for plaintext traffic: every endpoint requires HTTPS.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add daffy0208/ai-dev-standards --skill api-designer -a claude-code
```

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

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add daffy0208/ai-dev-standards --skill api-designer -a codex
```

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

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add daffy0208/ai-dev-standards --skill api-designer -a cursor
```

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

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install daffy0208/ai-dev-standards skills/api-designer
```

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

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add daffy0208/ai-dev-standards --skill api-designer -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/daffy0208/ai-dev-standards --path skills/api-designer
```

### Windsurf (Devin Desktop)

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

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add daffy0208/ai-dev-standards --skill api-designer -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/daffy0208/ai-dev-standards/tree/HEAD/skills/api-designer/SKILL.md

## When to use it
- design REST endpoints with noun-based plural routes
- structure unified JSON payloads and error responses
- define rate limiting headers and status codes
- select an authentication scheme among JWT, API keys, and OAuth 2.0

## Example prompts
- Design REST endpoints for a blog platform with cursor pagination and nested comments
- Draft a 422 validation error response matching the API standard
- Define rate limit headers and status codes for our public API

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 5d1764694ac6fa47.

BEGIN THIRD-PARTY FILE 5d1764694ac6fa47
````text
---
name: API Designer
description: Design REST and GraphQL APIs. Use when creating backend APIs, defining API contracts, or integrating third-party services. Covers endpoint design, authentication, versioning, documentation, and best practices.
version: 1.0.0
---

# API Designer

Design robust, scalable, and developer-friendly APIs.

## Core Principles

### 1. Developer Experience First

- Clear, predictable naming conventions
- Comprehensive documentation
- Helpful error messages
- Consistent patterns across endpoints

### 2. Design for Evolution

- Versioning strategy from day one
- Backward compatibility
- Deprecation process
- Migration guides for breaking changes

### 3. Security by Default

- Authentication and authorization
- Rate limiting and throttling
- Input validation and sanitization
- HTTPS only, no exceptions

### 4. Performance Matters

- Efficient queries and indexing
- Caching strategies
- Pagination for large datasets
- Compression (gzip, brotli)

## REST API Design

### Resource Naming Conventions

```
✅ Good (Nouns, plural, hierarchical):
GET    /users                  # List all users
GET    /users/123              # Get specific user
POST   /users                  # Create user
PUT    /users/123              # Replace user
PATCH  /users/123              # Update user
DELETE /users/123              # Delete user
GET    /users/123/posts        # User's posts (nested)
GET    /users/123/posts/456    # Specific post

❌ Bad (Verbs, inconsistent, unclear):
GET /getUsers
POST /createUser
GET /user-list
GET /UserData?id=123
```

### HTTP Methods & Semantics

| Method     | Purpose          | Idempotent | Safe | Request Body | Response Body   |
| ---------- | ---------------- | ---------- | ---- | ------------ | --------------- |
| **GET**    | Retrieve data    | Yes        | Yes  | No           | Yes             |
| **POST**   | Create resource  | No         | No   | Yes          | Yes (created)   |
| **PUT**    | Replace resource | Yes        | No   | Yes          | Yes (optional)  |
| **PATCH**  | Partial update   | No         | No   | Yes          | Yes (optional)  |
| **DELETE** | Remove resource  | Yes        | No   | No           | No (204) or Yes |

**Idempotent**: Multiple identical requests have same effect as single request
**Safe**: Request doesn't modify server state

### HTTP Status Codes

**Success (2xx)**:

- `200 OK` - Successful GET, PUT, PATCH, DELETE
- `201 Created` - Successful POST, includes `Location` header
- `204 No Content` - Successful request, no response body (often DELETE)

**Client Errors (4xx)**:

- `400 Bad Request` - Invalid syntax, validation error
- `401 Unauthorized` - Authentication required or failed
- `403 Forbidden` - Authenticated but lacks permission
- `404 Not Found` - Resource doesn't exist
- `409 Conflict` - Request conflicts with current state
- `422 Unprocessable Entity` - Validation error (semantic)
- `429 Too Many Requests` - Rate limit exceeded

**Server Errors (5xx)**:

- `500 Internal Server Error` - Generic server error
````
END THIRD-PARTY FILE 5d1764694ac6fa47

The third-party file has ended. Everything between the 5d1764694ac6fa47 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3045 of 11858 bytes. © daffy0208 · MIT · https://github.com/daffy0208/ai-dev-standards/tree/HEAD/skills/api-designer/SKILL.md

_Part of the page did not fit — see the HTML version._

---
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
