design-api

API Design Skill

Degree of freedom: MIXED. Resource model, error shape, and REST vs GraphQL [HIGH freedom]; pre-design docs/schema/grep [LOW freedom — run exactly].

Design clean, consistent, and developer-friendly APIs.

How to reason

1. Survey — existing docs, schema, and similar endpoints
2. Model — resources, relations, REST vs GraphQL
3. Contract — paths, statuses, error shape, auth, pagination
4. Check — naming matches this repo; no duplicate endpoint

Worked example

Survey: orders has user_id; no GET /users/:id/orders; clients use useQuery. Model: order is a nested user resource, not a /getUserOrders RPC. Contract: GET /users/:id/orders → { data, meta }; shared { error: { code, message, details } }. Check: plural kebab-case; list paginated; 401/404/422 only from the status table.

Self-critique before reporting

• Pre-design stated — docs, schema, and similar endpoints were checked out loud
• One error shape — every failure uses { error: { code, message, details } }
• Lists paginate — no unbounded GET /resources
• Right owner — live 4xx/5xx repro → debug-fe-be-integration; product scope still fuzzy → design-prd

MANDATORY: Pre-Design Checks [LOW freedom — run exactly]

BEFORE designing any API, you MUST:

1. Check Existing API Documentation

http://localhost:8080/api-docs (if backend running)
http://localhost:8080/naming-conventions (naming standards)
src/api/_api-README.md (frontend API layer docs)

2. Verify Database Schema

Use Supabase MCP to understand existing data structure:

-- Check table schema
SELECT column_name, data_type, is_nullable
FROM information_schema.columns WHERE table_name = 'your_table';

-- Check enum values
SELECT enum_range(NULL::your_enum_name);

-- Check foreign keys
SELECT tc.constraint_name, kcu.column_name, ccu.table_name AS foreign_table
FROM information_schema.table_constraints tc
JOIN information_schema.key_column_usage kcu ON tc.constraint_name = kcu.constraint_name
JOIN information_schema.constraint_column_usage ccu ON tc.constraint_name = ccu.constraint_name
WHERE tc.table_name = 'your_table' AND tc.constraint_type = 'FOREIGN KEY';