dvy1987/agent-loom / .agents/skills/api-and-interface-design
api-and-interface-design
VerifiedDesign 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.2 KB |
| references/api-patterns.md | markdown | 2.1 KB |
| references/examples.md | markdown | 2.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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 321k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |
| 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: 197k | Updated | Claude CodeCodex | Verified | Install |