API Designer Skill

Role

Backend developer who designs and implements RESTful APIs

API Design Principles

RESTful Rules

/api/resources

/api/resources/:id

/api/resources

/api/resources/:id

/api/resources/:id

/api/resources/:id

Response Format

// Success
{ data: T }
{ data: T[], total?: number }

// Error
{ error: string, details?: unknown }

HTTP Status Codes

Implementation Order

1. Type Definition (packages/shared)

// packages/shared/src/index.ts
export type CreateFeatureRequest = {
  name: string;
  description?: string;
};

export type FeatureResponse = {
  id: string;
  name: string;
  description: string | null;
  createdAt: string;
};

2. DB Schema (if needed)

// packages/db/src/schema.ts
export const features = sqliteTable('features', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  description: text('description'),
  createdAt: text('created_at').notNull(),
});

3. Route Implementation

// apps/server/src/routes/features.ts
import { Router } from 'express';
import { db } from '@local-review/db';
import { features } from '@local-review/db/schema';
import { nanoid } from 'nanoid';

const router = Router();

// GET /api/features
router.get('/', async (req, res) => {
  try {
    const result = await db.select().from(features);
    res.json(result);
  } catch (error) {
    res.status(500).json({ error: 'Failed to fetch features' });
  }
});

// POST /api/features
router.post('/', async (req, res) => {
  try {
    const { name, description } = req.body;

    if (!name) {
      return res.status(400).json({ error: 'Name is required' });
    }

    const newFeature = {
      id: nanoid(),
      name,
      description: description ?? null,
      createdAt: new Date().toISOString(),
    };

    await db.insert(features).values(newFeature);
    res.status(201).json(newFeature);
  } catch (error) {
    res.status(500).json({ error: 'Failed to create feature' });
  }
});

export default router;

4. Register Route

// apps/server/src/index.ts
import featuresRouter from './routes/features';
app.use('/api/features', featuresRouter);

5. Frontend API Client

// apps/web/src/lib/api.ts
export const featureApi = {
  list: () => fetchJson<FeatureResponse[]>('/api/features'),
  create: (data: CreateFeatureRequest) =>
    fetchJson<FeatureResponse>('/api/features', {
      method: 'POST',
      body: JSON.stringify(data),
    }),
};

Existing API Reference

Current project API structure:

• GET /api/git/branches

  - Branch list

• GET/POST /api/sessions

  - Session CRUD

• GET/POST /api/sessions/:id/comments

  - Comments

• PATCH /api/sessions/:id/files/*/status

  - File status