api-design-typescript

API Design for TypeScript/Node.js

Extends core/rules/api-design.mdc with TypeScript and Node.js specific patterns.

---

Framework Selection

Express (Simple, flexible)

import express, { Request, Response, NextFunction } from 'express';

const app = express();

app.get('/api/users/:id', async (req: Request, res: Response, next: NextFunction) => {
  try {
    const user = await userService.getUser(parseInt(req.params.id));
    res.json(user);
  } catch (error) {
    next(error);
  }
});

NestJS (Enterprise, opinionated)

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get(':id')
  @ApiResponse({ status: 200, type: UserDto })
  @ApiResponse({ status: 404, description: 'User not found' })
  async getUser(@Param('id', ParseIntPipe) id: number): Promise<UserDto> {
    return this.usersService.findOne(id);
  }
}

Fastify (Fast, low overhead)

import Fastify from 'fastify';

const fastify = Fastify({ logger: true });

fastify.get<{ Params: { id: string } }>('/api/users/:id', async (request, reply) => {
  const user = await userService.getUser(parseInt(request.params.id));
  return user;
});

---

Type-Safe Request/Response

Zod Validation

import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email().max(255),
  name: z.string().min(2).max(100),
  age: z.number().int().min(18).optional(),
});

type CreateUserDto = z.infer<typeof CreateUserSchema>;

// Middleware
const validate = (schema: z.ZodSchema) => {
  return (req: Request, res: Response, next: NextFunction) => {
    try {
      schema.parse(req.body);
      next();
    } catch (error) {
      if (error instanceof z.ZodError) {
        res.status(400).json({ errors: error.errors });
      }
    }
  };
};

// Usage
app.post('/api/users', validate(CreateUserSchema), async (req, res) => {
  const userData = req.body as CreateUserDto;
  // ...
});