api-design

name	api-design
description	Use this skill when designing, reviewing, or refactoring REST APIs in WrongStack. Triggers: user says "API", "endpoint", "REST", "request", "response", "JSON", "HTTP", "status code", "pagination", "query params", "request body".
version	1.1.0
required-capabilities	["filesystem.read"]
required-tools	[]
optional-capabilities	["filesystem.write","verification.run"]

API Design — WrongStack

Overview

Designs and reviews REST APIs for WrongStack services. WrongStack uses JSON over HTTPS, conventional HTTP status codes, and cursor-based pagination. APIs are consumed by the TUI, webui, and external integrations.

Rules

1. Use conventional HTTP status codes: 200 (ok), 201 (created), 400 (bad request), 401 (unauthorized), 403 (forbidden), 404 (not found), 500 (server error).
2. Always return consistent error shape: { "error": { "code": "ERROR_CODE", "message": "Human readable" } }.
3. Use plural nouns for resource names: /sessions not /session.
4. Pagination: cursor-based for large datasets, not offset-based.
5. Request validation: validate on server, return 400 with field-level errors.
6. Idempotency: POST to /resources creates; PUT to /resources/:id replaces.
7. No secrets in URLs — put auth in headers, not query params.
8. Versioning: prefix with /v1/ when breaking changes are inevitable.

Patterns

Do

// ✅ Consistent error shape
interface ErrorResponse {
  error: {
    code: string; // machine-readable: "VALIDATION_ERROR"
    message: string;    // human-readable: "name is required"
    details?: unknown;  // optional field-level errors
  };
}

// ✅ Cursor-based pagination
interface PaginatedResponse<T> {
  data: T[];
  nextCursor: string | null;  // null = last page
  hasMore: boolean;
}

// GET /sessions?cursor=abc123&limit=20

// ✅ Proper status codes
if (!resource) return Response.json({ error: { code: 'NOT_FOUND', message: '...' } }, { status: 404 });
if (!auth) return Response.json({ error: { code: 'UNAUTHORIZED', message: '...' } }, { status: 401 });

Don't

// ❌ Inconsistent error shape
Response.json({ message: 'Not found' }); // no code, no standard shape

// ❌ Secrets in URL
GET /api/data?apiKey=sk-xxx  // ❌ put in Authorization header

// ❌ Offset pagination (fragile on mutations)
GET /users?offset=100&limit=20  // ❌ gaps after insert/delete

// ❌ 200 for errors
Response.json({ error: '...' }, { status: 200 }); // lies about outcome

Request/response patterns

Create resource (POST)

POST /sessions
Body: { "provider": "anthropic", "model": "<model-id>" }
201: { "id": "sess_abc", "provider": "anthropic", ... }
400: { "error": { "code": "VALIDATION_ERROR", "message": "model is required" } }

Get resource (GET)

GET /sessions/sess_abc
200: { "id": "sess_abc", "status": "running", ... }
404: { "error": { "code": "NOT_FOUND", "message": "Session not found" } }

List with pagination

GET /sessions?cursor=sess_xyz&limit=20
200: {
  "data": [...],
  "nextCursor": "sess_aaa",
  "hasMore": true
}

Update resource (PUT)

PUT /sessions/sess_abc
Body: { "status": "paused" }
200: { "id": "sess_abc", "status": "paused", ... }
400: { "error": { "code": "INVALID_STATUS", "message": "Must be running or paused" } }

Error codes

Code	HTTP	When
VALIDATION_ERROR	400	Request body/params invalid
UNAUTHORIZED	401	Missing or invalid auth
FORBIDDEN	403	Auth valid but no permission
NOT_FOUND	404	Resource doesn't exist
CONFLICT	409	Duplicate resource
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server-side failure

Authentication

• Bearer token in Authorization header: Authorization: Bearer <token>
• API key in X-API-Key header for machine-to-machine
• Never use query params for auth credentials

WrongStack-specific notes

• WrongStack CLI: Most API calls go through the CLI's internal tool wrappers, not raw HTTP.
• Session management: Sessions are created/managed via the CLI, not a public REST API.
• MCP tools: MCP servers expose tools, not REST endpoints — this skill is for any HTTP APIs WrongStack exposes.

Out of scope

• Don't design MCP tool surfaces here. MCP servers expose tools, not REST endpoints. For tool registration, plugin contract, and tool description, see the plugin-author skill instead.
• Don't design WrongStack session management as a public API. Sessions are created and managed through the CLI's internal tool wrappers, not a public REST surface. This skill is for the HTTP APIs WrongStack exposes outward.
• Don't ship inconsistent error shapes. Every error uses { "error": { "code", "message", "details?" } }. Variations break automation that depends on the shape.
• Don't put secrets in URLs. ?apiKey=… is a leak. Headers — Authorization and X-API-Key — are the only auth channels.
• Don't use offset pagination for large datasets. Cursor-based only. Offset pagination breaks on insert/delete; gaps and duplicates follow.
• Don't return 200 for errors. The status code is the contract; 200 with an error body lies about the outcome. Use the right code.
• Don't use singular nouns for collections. /sessions not /session. The resource is the set; the item is /sessions/:id.
• Don't ship breaking changes without a /v1/ prefix. Versioning is a contract with the consumer; renames are breaking.
• Don't accept client-side validation as a substitute. Validate on the server, return 400 with field-level errors. The client is an untrusted input source.

Before returning

• Conventional HTTP status codes used; no 200 for errors
• Error shape consistent: { "error": { "code", "message", "details? } }
• Plural nouns for resources; /v1/ prefix for breaking-change endpoints
• Cursor-based pagination for large datasets, not offset
• Auth in headers (Authorization: Bearer, X-API-Key); no secrets in URLs
• Server-side validation with 400 + field-level errors
• Idempotency rules followed: POST creates, PUT replaces
• sdd spec opened for non-trivial endpoints before coding
• security-scanner run on the implementation
• <nextsteps> mirrors the open follow-ups in priority order

Skills in scope

• sdd — for spec-driven API design with acceptance criteria
• typescript-strict — for type-safe request/response types
• security-scanner — for scanning API implementations for injection, auth, and secrets
• testing — for writing integration tests against API endpoints
• output-standards — for standardized <nextsteps> formatting