API Design Skill

Design clean, consistent, and developer-friendly APIs.

MANDATORY: Pre-Design Checks

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

3. Check for Existing Endpoints

Use Grep to search for similar endpoints already implemented:

Grep: "router.get|router.post" to find existing route patterns
Grep: "useQuery|useMutation" to find existing frontend integrations

4. Verification Statement (REQUIRED)

Before designing, state:

"Pre-design check:
- Existing API docs reviewed: [YES/NO]
- Database schema verified: [tables/enums checked]
- Similar endpoints found: [list or none]
- Naming conventions confirmed: [YES/NO]"

REST API Design

URL Structure

GET /resources # List
GET /resources/:id # Get one
POST /resources # Create
PUT /resources/:id # Replace
PATCH /resources/:id # Update
DELETE /resources/:id # Delete

Naming Conventions

Examples

GET /users # List users
GET /users/123 # Get user 123
GET /users/123/orders # User's orders
GET /users/123/orders/456 # Specific order
POST /users/123/orders # Create order for user

Request/Response Format

Request Body

{
 "name": "John Doe",
 "email": "[email protected]",
 "role": "admin"
}

Successful Response

{
 "data": {
 "id": "123",
 "name": "John Doe",
 "email": "[email protected]",
 "createdAt": "2024-01-15T10:30:00Z"
 }
}

List Response (with pagination)

{
 "data": [
 { "id": "1", "name": "John" },
 { "id": "2", "name": "Jane" }
 ],
 "meta": {
 "total": 100,
 "page": 1,
 "perPage": 20,
 "totalPages": 5
 }
}

Error Response

{
 "error": {
 "code": "VALIDATION_ERROR",
 "message": "Invalid input data",
 "details": [
 { "field": "email", "message": "Invalid email format" },
 { "field": "name", "message": "Name is required" }
 ]
 }
}

HTTP Status Codes

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

Query Parameters

Filtering

GET /users?role=admin
GET /users?role=admin&status=active
GET /orders?createdAfter=2024-01-01

Sorting

GET /users?sort=name # Ascending
GET /users?sort=-createdAt # Descending (prefix with -)
GET /users?sort=role,-name # Multiple fields

Pagination

GET /users?page=2&perPage=20
GET /users?offset=40&limit=20
GET /users?cursor=abc123 # Cursor-based

Field Selection

GET /users?fields=id,name,email
GET /users?include=orders,profile

Versioning

URL Path (Recommended)

GET /v1/users
GET /v2/users

Header

GET /users
Accept: application/vnd.api+json;version=2

Authentication

Bearer Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key

X-API-Key: your-api-key
# or
?apiKey=your-api-key

Common Patterns

Bulk Operations

POST /users/bulk
{
 "create": [{ "name": "John" }, { "name": "Jane" }],
 "update": [{ "id": "1", "name": "Updated" }],
 "delete": ["2", "3"]
}

Search

POST /users/search
{
 "query": "john",
 "filters": { "role": "admin" },
 "sort": { "field": "name", "order": "asc" }
}

Actions (non-CRUD)

POST /orders/123/cancel
POST /users/123/verify-email
POST /payments/123/refund

API Design Checklist

Consistency

• [ ] Consistent naming conventions
• [ ] Consistent response format
• [ ] Consistent error format
• [ ] Consistent pagination

Usability

• [ ] Intuitive URLs
• [ ] Clear documentation
• [ ] Meaningful error messages
• [ ] Sensible defaults

Security

• [ ] Authentication required
• [ ] Authorization checked
• [ ] Input validation
• [ ] Rate limiting

Performance

• [ ] Pagination for lists
• [ ] Field selection available
• [ ] Efficient queries
• [ ] Caching headers

Documentation Template

## Create User

Create a new user account.

**Endpoint:** `POST /users`

**Authentication:** Required (Bearer token)

**Request Body:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| name | string | Yes | User's full name |
| email | string | Yes | Valid email address |
| role | string | No | User role (default: "user") |

**Response:** `201 Created`
\`\`\`json
{
 "data": {
 "id": "123",
 "name": "John Doe",
 "email": "[email protected]",
 "role": "user",
 "createdAt": "2024-01-15T10:30:00Z"
 }
}
\`\`\`

**Errors:**
- `400` - Invalid request body
- `409` - Email already exists
- `422` - Validation failed