TypeScript API Design

Comprehensive guide to designing type-safe APIs with TypeScript. Covers type-safe contracts, validation with Zod, Result types for error handling, SvelteKit endpoints, middleware patterns and API versioning.

When This Skill Applies

Use this skill when:

Designing API endpoints
Creating type-safe API contracts
Implementing validation
Handling API errors
Building SvelteKit API routes
Creating reusable middleware
Versioning APIs
Questions about API design patterns

Type-Safe Contracts

Request/Response Types

// types/api.ts
export interface CreateUserRequest {
    email: string;
    name: string;
    password: string;
}

export interface User {
    id: string;
    email: string;
    name: string;
    createdAt: string;
}

export interface ApiError {
    code: string;
    message: string;
    details?: Record<string, string[]>;
}

Key principle: Types ARE documentation. Well-named types with clear structure tell the story.

Result Type Pattern

// For expected failures (not found, validation, etc.)
export type Result<T, E = string> =
    | { success: true; data: T }
    | { success: false; error: E };

// Usage
function findUser(id: string): Result<User, 'not_found'> {
    const user = db.findUser(id);
    if (!user) {
        return { success: false, error: 'not_found' };
    }
    return { success: true, data: user };
}

// Consuming
const result = findUser('123');
if (result.success) {
    console.log(result.data.email); // Type-safe access
} else {
    console.error('Error:', result.error);
}

API Response Format

// Standard success response
export interface ApiSuccess<T> {
    success: true;
    data: T;
}

// Standard error response
export interface ApiError {
    success: false;
    error: {
        code: string;
        message: string;
        details?: Record<string, string[]>;
    };
}

export type ApiResponse<T> = ApiSuccess<T> | ApiError;

Endpoint Type Map

// Optional: Define all endpoints in one place
export interface ApiEndpoints {
    'POST /api/users': {
        request: CreateUserRequest;
        response: User;
    };
    'GET /api/users/:id': {
        params: { id: string };
        response: User;
    };
    'PATCH /api/users/:id': {
        params: { id: string };
        request: Partial<UpdateUserRequest>;
        response: User;
    };
    'DELETE /api/users/:id': {
        params: { id: string };
        response: null;
    };
}

Additional resources

Deep-dive detail lives in supporting files, loaded only when needed:

validation-and-errors.md: Zod schemas, Result types vs. Error classes, centralised error handling
sveltekit-and-middleware.md: GET/POST/PATCH/DELETE endpoint patterns, auth/validation/rate-limit/composed middleware
auth-and-database.md: cookie/JWT/Supabase session patterns, typed PostgreSQL and Neo4j wrappers
versioning-and-clients.md: URL-based versioning, type-safe API clients, OpenAPI generation, endpoint/business-logic testing
privacy.md: response filtering, request minimisation, sensitive-data handling, auth scoping, data deletion

Best Practices

1. Always Validate Input

// ✓ Good - validate with Zod
const data = CreateUserSchema.parse(input);
const user = await createUser(data);

// ✗ Bad - trusting client input
const user = await createUser(input);

2. Use Result Types for Expected Failures

// ✓ Good - Result type for expected failure
function findUser(id: string): Result<User, 'not_found'> {
    const user = db.findUser(id);
    if (!user) {
        return { success: false, error: 'not_found' };
    }
    return { success: true, data: user };
}

// ✗ Bad - throwing for expected case
function findUser(id: string): User {
    const user = db.findUser(id);
    if (!user) throw new Error('Not found');
    return user;
}

3. Throw Error Classes for Unexpected Failures

// ✓ Good - throw for exceptional case
async function connectDatabase(): Promise<Database> {
    try {
        return await connect();
    } catch (error) {
        throw new DatabaseError('Failed to connect');
    }
}

// ✗ Bad - Result type for exceptional case
async function connectDatabase(): Result<Database, string> {
    // Database connection should succeed or crash
}

4. Type Everything Explicitly

// ✓ Good - explicit types
interface CreateUserRequest {
    email: string;
    name: string;
}

async function createUser(data: CreateUserRequest): Promise<User> {
    // ...
}

// ✗ Bad - implicit any
async function createUser(data): Promise<any> {
    // ...
}

5. Separate Concerns (Layered Architecture)

// ✓ Good - separated layers

// Handler (thin, delegates to service)
export const POST: RequestHandler = async ({ request }) => {
    const data = await validateRequest(request, CreateUserSchema);
    const user = await createUser(data);
    return json({ success: true, data: user }, { status: 201 });
};

// Service (business logic)
async function createUser(data: CreateUserRequest): Promise<User> {
    const passwordHash = await hashPassword(data.password);
    return await db.users.create({ ...data, passwordHash });
}

// ✗ Bad - everything in handler
export const POST: RequestHandler = async ({ request }) => {
    const body = await request.json();
    // validation, hashing, database, all mixed together
};

6. Use Middleware for Cross-Cutting Concerns

// ✓ Good - reusable middleware
export const POST: RequestHandler = async (event) => {
    const user = await requireAuth(event);
    const data = await validateRequest(event.request, CreatePostSchema);
    const post = await createPost(user.id, data);
    return json({ success: true, data: post });
};

// ✗ Bad - repeating auth/validation everywhere
export const POST: RequestHandler = async ({ request, cookies }) => {
    // Repeated auth code
    const session = cookies.get('session');
    if (!session) throw error(401);
    const user = await verifySession(session);

    // Repeated validation code
    const body = await request.json();
    if (!body.title) throw error(400);
    // ...
};

7. Document with Types, Not Comments

// ✓ Good - type tells the story
interface CreateUserRequest {
    email: string;          // Type is clear
    name: string;           // Type is clear
    password: string;       // Min 8 chars (Zod enforces)
}

// ✗ Bad - relying on comments
interface CreateUserRequest {
    email: string;          // Must be valid email
    name: string;           // Required, 2-100 chars
    password: string;       // Min 8, uppercase, lowercase, number, special
}
// Comments get out of sync with code!

Success Criteria

API design is well-structured when:

All requests/responses explicitly typed
Input validated with Zod schemas
Expected failures use Result types
Unexpected failures throw Error classes
Endpoints follow REST conventions
Middleware reusable and composable
Database layer has typed wrappers
Authentication consistent across endpoints
Errors have standardised format
Type-safe client available for consumption
Tests cover happy path and error cases
Code is maintainable and follows patterns
Responses expose minimum necessary data (privacy-by-default)
No sensitive data logged or leaked
Auth scoping prevents cross-user data access
Data deletion is supported and complete

Role: API Designer

Files6

SKILL.mdskills/clod-role-api_designer/SKILL.md