Zodios
Zodios is a typescript api client and an optional api server with auto-completion features backed by axios and zod and express
Documentation
zodios.mp4
What is it ?
It's an axios compatible API client and an optional expressJS compatible API server with the following features:
- really simple centralized API declaration
- typescript autocompletion in your favorite IDE for URL and parameters
- typescript response types
- parameters and responses schema thanks to zod
- response schema validation
- bearer token injection and token renewal with simple token provider interface
- all axios features available
- all expressJS features available (middlewares, etc.)
Table of contents:
- What is it ?
- Install
- How to use it on client side ?
- Full documentation
- Ecosystem
- Roadmap
- Dependencies
Install
Client and api definitions :
> npm install @zodios/core
or
> yarn add @zodios/core
Server :
> npm install @zodios/core @zodios/express
or
> yarn add @zodios/core @zodios/express
How to use it on client side ?
For an almost complete example on how to use zodios and how to split your APIs declarations, take a look at dev.to example.
Declare your API with zodios
Here is an example of API declaration with Zodios.
import { Zodios } from "@zodios/core";
import { z } from "zod";
const apiClient = new Zodios(
"https://jsonplaceholder.typicode.com",
// API definition
[
{
method: "get",
path: "/users/:id", // auto detect :id and ask for it in apiClient get params
alias: "getUser", // optionnal alias to call this endpoint with it
description: "Get a user",
response: z.object({
id: z.number(),
name: z.string(),
}),
},
],
);
Calling this API is now easy and has builtin autocomplete features :
// typed auto-complete path auto-complete params
// ▼ ▼ ▼
const user = await apiClient.get("/users/:id", { params: { id: 7 } });
console.log(user);
It should output
{ id: 7, name: 'Kurtis Weissnat' }
You can also use aliases :
// typed alias auto-complete params
// ▼ ▼ ▼
const user = await apiClient.getUser({ params: { id: 7 } });
console.log(user);
API definition format
type ZodiosEndpointDescriptions = Array<{
method: 'get'|'post'|'put'|'patch'|'delete';
path: string; // example: /posts/:postId/comments/:commentId
alias?: string; // example: getPostComments
description?: string;
requestFormat?: 'json'|'form-data'|'form-url'|'binary'|'text'; // default to json if not set
parameters?: Array<{
name: string;
description?: string;
type: 'Query'|'Body'|'Header';
schema: ZodSchema; // you can use zod `transform` to transform the value of the parameter before sending it to the server
}>;
response: ZodSchema; // you can use zod `transform` to transform the value of the response before returning it
errors?: Array<{
status: number | 'default';
description?: string;
schema: ZodSchema; // transformations are not supported on error schemas
}>;
}>;
Full documentation
Check out the full documentation or following shortcuts.
Ecosystem
- openapi-zod-client: generate a zodios client from an openapi specification
- @zodios/express: full end to end type safety like tRPC, but for REST APIs
- @zodios/plugins : some plugins for zodios
- @zodios/react : a react-query wrapper for zodios
Roadmap
The following will need investigation to check if it's doable :
- implement
@zodios/nestjs
to define your API endpoints with nestjs and share it with your frontend (like tRPC) - generate openAPI json from your API endpoints
You have other ideas ? Let me know !
Dependencies
Zodios do not embed any dependency. It's your Job to install the peer dependencies you need.
Internally Zodios uses these libraries on all platforms :
- zod
- axios
In addition, it also uses on NodeJS :
- formdata-node
- form-data-encoder