Toolkit
Beta

API Routes

Pre-built RESTful endpoints for waitlist operations with request validation and error handling.

Add Email to Waitlist

POST
/api/waitlist
PropertyTypeExample
emailstring requireduser@example.com
referredByCodestringdBjd8-Xk

Types

app/api/waitlist/types.ts
import { z } from 'zod';
 
export const WaitlistSignupSchema = z.object({
  email: z.string().email(),
  referredByCode: z.string().optional(),
});
export type WaitlistSignup = z.infer<typeof WaitlistSignupSchema>;
 
export type PublicWaitlistEntry = {
  id: string;
  referralCode: string;
  referralUrl: string;
  createdAt: string;
};

Route Handler

app/api/waitlist/route.ts
import { NextResponse } from 'next/server';
 
/**
 * POST /api/waitlist
 * Signs up a user to the waitlist.
 */
export const POST = async (req: Request) => {
  const input = WaitlistSignupSchema.safeParse(await req.json());
 
  if (!input.success) {
    return NextResponse.json({ error: 'Invalid request.' }, { status: 400 });
  }
 
  const { email, referredByCode } = input.data;
  const service = new WaitlistService();
 
  try {
    const result = await service.addToWaitlist({ email, referredByCode });
    const response: PublicWaitlistEntry = {
      id: result.id,
      referralCode: result.referralCode,
      referralUrl: service.getReferralUrl(result.referralCode),
      createdAt: result.createdAt.toISOString(),
    };
    return NextResponse.json(response, { status: 201 });
  } catch (error) {
    console.error('Unexpected server error.', error);
    return NextResponse.json({ error: 'Something went wrong. Please try again.' }, { status: 500 });
  }
};

Key Design Decisions

  1. Uses Zod for runtime input validation and type inference.
  2. Returns minimal public information in responses for security.
  3. Handles referral tracking as an optional flow.
  4. Returns ISO formatted dates for universal compatibility.
  5. Implements standardized error responses with appropriate HTTP status codes.
  6. Separates type definitions from route logic for better maintainability.

On this page