Write typesafe APIs with zodios

Writing client APIs, that gives you autocompletion is time consuming. You allways endup writing the same kind of boilerplate code or have to use openapi code generators that are a pain to maintain.

Zodios was created to make creating frontend (and optionally backend) API client a breeze.
It's is an open source REST API toolbox with end-to-end typesafety.
It allows you to create a REST API with a clean, intuitive and declarative syntax.
It's best used with TypeScript, but it's also usable with pure JavaScript.

Declaring returned data with zod

You can predefine some schemas to reuse them in your API definition. Zodios will use these definition to make runtime checks. Your API client is then typesafe at runtime.

import { Zodios, asErrors } from "@zodios/core";
import z from "zod";

const errors = asErrors([
  {
    status: "default",
    schema: z.object({
      error: z.object({
        code: z.number(),
        message: z.string(),
      }),
    }),
  },
]);

const user = z.object({
  id: z.number(),
  name: z.string(),
  age: z.number().positive(),
  email: z.string().email(),
});

Declaring your API endpoints

Then you can define your API endpoints directly in the Zodios constructor.

const apiClient = new Zodios('/api', [
  {
    method: "get",
    path: "/users",
    alias: "getUsers",
    parameters: [
      {
        name: "limit",
        type: "Query",
        schema: z.number().positive().default(10),
      },
      {
        name: "page",
        type: "Query",
        schema: z.number().positive().default(0),
      },
    ],
    response: z.object({
      nextPage: z.number(),
      users: z.array(user),
    }),
  },
  {
    method: "get",
    path: "/users/:id",
    alias: "getUser",
    response: user,
    errors,
  },
  {
    method: "post",
    path: "/users",
    alias: "createUser",
    parameters: [
      {
        name: "user",
        type: "Body",
        schema: user.omit({ id: true }),
      },
    ],
    response: user,
    errors,
  },  
]);

Calling your APIs

And finally you can use it to fetch data from your API.

// get all users
const users = await apiClient.getUsers();
// get user by id
const user = await apiClient.getUser({ params: { id: 1 } });
// create user
const newUser = await apiCLient.createUser({ name: "John", age: 20, email: "[e-mail]"});

Using Zodios with React

Zodios provides you react hooks based on react-query. Zodios manages your query keys, for you, no need to handle them by hand.

const zodiosHooks = new ZodiosHooks("myAPI", apiClient);

const Users = () => {
  const {
    data: users,
    isLoading,
    error,
    fetchNextPage,
    invalidate: invalidateUsers, // zodios also provides invalidation helpers
  } = zodiosHooks.useInfiniteQuery(
    "/users",
    { queries: { limit: 10 } },
    {
      getPageParamList: () => {
        return ["page"];
      },
      getNextPageParam: () => {
        return {
          queries: {
            page: page.nextPage + 1,
          },
        };
      },
    }
  );
  const { mutate } = zodiosHooks.useCreateUser(undefined, {
    onSuccess: () => invalidateUsers(),
  });

  return (
    <>
      <h1>Users</h1>
      <button onClick={() => mutate({ name: "john doe" })}>add user</button>
      {isLoading && <div>Loading...</div>}
      {error && <div>Error: {(error as Error).message}</div>}
      {users && (
        <>
          <ul>
            {users.pages.flatMap((page) =>
              page.map((user) => <li key={user.id}>{user.name}</li>)
            )}
          </ul>
          <button onClick={() => fetchNextPage()}>more</button>
        </>
      )}
    </>
  );
};

What's next

Zodios has much more tools under the hood.
API client has a powerfull plugin system.
Zodios also provides an 'express' adapter, so you can also create your server APIs safely with nodeJS.
It integrates also nicely with 'NextJS'.

Take a look a zodios website