API Handlers

Convention

All handlers follow the handle[Resource][Method] pattern:

• handleUserGet - GET user
• handleEventCreate - POST event
• handleOrderPut - PUT order

Structure

Handlers use createRoute() with Zod schemas to auto-generate OpenAPI specs.

import { createRoute } from '@hono/zod-openapi';

const route = createRoute({
  method: 'get',
  path: '/event/:id',
  request: {
    params: eventZodParams,
  },
  responses: {
    200: {
      content: {
        'application/json': {
          schema: eventZodRead,
        },
      },
      description: 'Event found',
    },
  },
});

Response format

All responses follow the standard format:

{
  success: boolean;
  data?: T;
  error?: string;
}

Mappers

Mappers convert MongoDB documents to the API format (Zod inferred types):

const eventMapper = async (doc: EventDocument): Promise<EventRead> => {
  return {
    _id: doc._id.toString(),
    name: doc.name,
    // ...
  };
};

Mappers are always async functions.