Skip to content

dvy1987/agent-loom / .agents/skills/api-and-interface-design

api-and-interface-design

Verified

Design stable APIs and module boundaries — contract-first types, consistent errors, boundary validation, additive changes. Load when designing REST or GraphQL endpoints, public module interfaces, component props, or FE/BE contracts. Also triggers on "API design", "interface design", "design the API", "module boundary", "API contract", "define the interface". Complements feature-spec (product layer). Routes breaking retirement to api-deprecation-and-migration when it exists.

FileKindSize
SKILL.mdskill md5.2 KB
references/api-patterns.mdmarkdown2.1 KB
references/examples.mdmarkdown2.3 KB

references/api-patterns.md

View on GitHub
# API patterns (api-and-interface-design)

## REST resources

```
GET    /api/tasks              → List (paginated)
POST   /api/tasks              → Create
GET    /api/tasks/:id          → Get one
PATCH  /api/tasks/:id          → Partial update
DELETE /api/tasks/:id          → Delete (idempotent OK)

GET    /api/tasks/:id/comments → Sub-resource list
POST   /api/tasks/:id/comments → Create sub-resource
```

Avoid verbs in URLs: `/api/createTask` → `POST /api/tasks`.

## Pagination response

```json
{
  "data": [],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 142,
    "totalPages": 8
  }
}
```

Query: `?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc`

## Error body (consistent everywhere)

```typescript
interface APIError {
  error: {
    code: string;      // VALIDATION_ERROR
    message: string;   // Human-readable
    details?: unknown;
  };
}
```

| Status | Use |
|--------|-----|
| 400 | Malformed request |
| 401 | Not authenticated |
| 403 | Not authorized |
| 404 | Not found |
| 409 | Conflict |
| 422 | Semantic validation failed |
| 500 | Server error (no internal leak) |

## TypeScript patterns

```typescript
interface CreateTaskInput {
  title: string;
  description?: string;
  priority?: 'low' | 'medium' | 'high'; // additive optional
}

interface Task {
  id: string;
  title: string;
  description: string | null;
  createdAt: Date;
  updatedAt: Date;
}

type TaskId = string & { readonly __brand: 'TaskId' };

type TaskStatus =
  | { type: 'pending' }
  | { type: 'in_progress'; assignee: string }
  | { type: 'completed'; completedAt: Date };
```

## Boundary validation example

```typescript
app.post('/api/tasks', async (req, res) => {
  const result = CreateTaskSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(422).json({
      error: { code: 'VALIDATION_ERROR', message: 'Invalid task data', details: result.error.flatten() },
    });
  }
  const task = await taskService.create(result.data);
  return res.status(201).json(task);
});
```

Internal service code trusts `result.data` — no re-validation.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 321kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 197kUpdated Claude CodeCodexVerifiedInstall