Endpoint

Individual API endpoints with input/output validation

Overview

Endpoints are created using EndpointsFactory.build() and represent individual API routes with typed input/output schemas and handler functions.

import { defaultEndpointsFactory } from "express-zod-api";
import { z } from "zod";

const getUser = defaultEndpointsFactory.build({
  method: "get",
  input: z.object({
    id: z.string(),
  }),
  output: z.object({
    id: z.string(),
    name: z.string(),
    email: z.string().email(),
  }),
  handler: async ({ input, logger }) => {
    logger.info(`Fetching user ${input.id}`);
    return await db.users.findById(input.id);
  },
});

Configuration Options

method

Type: Method | Method[]

Default: "get"

HTTP method(s) the endpoint handles.

method: "post"
method: ["get", "post"]

input

Type: ZodObject

Default: z.object({})

Input validation schema.

output

Type: ZodType

Required: Yes

Output validation schema.

handler

Type: Handler<Input, Output, Context>

Required: Yes

Async function that processes the request.

handler: async ({ input, ctx, logger, request, response }) => {
  return { result: "success" };
}

shortDescription

Type: string

Brief summary for OpenAPI documentation (max 50 characters).

description

Type: string

Detailed description for OpenAPI documentation.

operationId

Type: string | ((method: ClientMethod) => string)

Unique operation identifier for documentation.

tag

Type: Tag | Tag[]

Tags for organizing documentation.

scope

Type: string | string[]

OAuth2 scopes required for the endpoint.

deprecated

Type: boolean

Marks the endpoint as deprecated in documentation.

Handler Parameters

The handler function receives an object with:

input · Input

Validated input from request (query, body, params, etc.)

ctx · Context

Context accumulated from middleware

logger · Logger

Logger instance (child logger if configured)

request · Request

Express request object

response · Response

Express response object

Examples

Basic GET Endpoint

const listUsers = defaultEndpointsFactory.build({
  method: "get",
  input: z.object({
    limit: z.string().transform(Number).pipe(z.number().int().positive()),
    offset: z.string().transform(Number).pipe(z.number().int().nonnegative()).optional(),
  }),
  output: z.object({
    users: z.array(z.object({
      id: z.string(),
      name: z.string(),
    })),
    total: z.number(),
  }),
  handler: async ({ input }) => {
    const users = await db.users.find().limit(input.limit).skip(input.offset || 0);
    const total = await db.users.count();
    return { users, total };
  },
});

POST Endpoint with Authentication

const createPost = authFactory.build({
  method: "post",
  input: z.object({
    title: z.string().min(1).max(200),
    content: z.string().min(1),
    tags: z.array(z.string()).optional(),
  }),
  output: z.object({
    id: z.string(),
    createdAt: ez.dateOut(),
  }),
  handler: async ({ input, ctx: { user } }) => {
    const post = await db.posts.create({
      ...input,
      authorId: user.id,
    });
    return { id: post.id, createdAt: post.createdAt };
  },
});

See Also

EndpointsFactory

Create endpoint factories

Routing

Attach endpoints to routes