Validating the API inputs with Zod and Typescript

Zod is a library for validating data with awesome support for Typescript. Learn how to use it within your Makerkit project.

Zod is a Typescript library that helps us secure our API endpoints by validating the payloads sent from the client and also facilitating the typing of the payloads with Typescript.

Using Zod is the first line of defense to validate the data sent against our API: as a result, it's something we recommend you keep doing. It ensures we write safe, resilient, and valid code.

All Makerkit's API routes are secured with Zod: in this document, we want to explain the conventions used by the SaaS Boilerplate, and how to use it for your API endpoints.

When we write an API endpoint, we first define the schema of the payload:

tsx

function getBodySchema() {
  return z.object({
    displayName: z.string(),
    email: z.string().email(),
  });
}

This function represents the schema, which will validate the following interface:

tsx

interface Body {
  displayName: string;
  email: Email;
}

Now, let's write the body of the API handler that validates the body of the function, which we expect to be equal to the Body interface.

tsx

import { throwBadRequestException } from `~/core/http-exceptions`;
function inviteMemberHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  try {
     // we can safely use data with the interface Body
    const schema = getBodySchema();
    const { displayName, email } = schema.parse(req.body);
    return sendInvite({ displayName, email });
  } catch(e) {
    return throwBadRequestException(res);
  }
}
export default function apiHandler() {
  const handler = withPipe(
    withMethodsGuard(['POST']),
    withAuthedUser,
    inviteMemberHandler,
  );
  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}

You can also use safeParse if you prefer not to throw an error when the validation fails:

tsx

function inviteMemberHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const schema = getBodySchema();
  const result = schema.safeParse(req.body);
  // we use result.success as a type guard
  // when false, we throw an exception
  if (!result.success) {
    return throwBadRequestException(res);
  }
  // TS correctly infers result.data now
  return sendInvite(result.data);
}

To learn more about validating data with Zod, we suggest you check out the Zod official documentation on GitHub.

import { throwBadRequestException } from `~/core/http-exceptions`; function inviteMemberHandler( req: NextApiRequest, res: NextApiResponse, ) { try { // we can safely use data with the interface Body const schema = getBodySchema(); const { displayName, email } = schema.parse(req.body); return sendInvite({ displayName, email }); } catch(e) { return throwBadRequestException(res); } } export default function apiHandler() { const handler = withPipe( withMethodsGuard(['POST']), withAuthedUser, inviteMemberHandler, ); // manage exceptions return withExceptionFilter(req, res)(handler); }

function inviteMemberHandler( req: NextApiRequest, res: NextApiResponse, ) { const schema = getBodySchema(); const result = schema.safeParse(req.body); // we use result.success as a type guard // when false, we throw an exception if (!result.success) { return throwBadRequestException(res); } // TS correctly infers result.data now return sendInvite(result.data); }