Skip to main content

API definition

Zodios uses a centralised definition to declare your REST API endpoints.

The API definition is the only object that you need to share between your server and client code. If you don't have the control over your API server or if it's developped in another language than javascript, you can still use Zodios API definition only for your client.

API Definition Structure

The API definition is a javascript array of endpoint descriptions. Each endpoint description is an object with the following properties:

PropertyTypeDescription
methodstringThe HTTP method of the endpoint.
pathstringThe path of the endpoint.
responseZodSchemaThe response Schema of the endpoint using Zod.
statusnumberThe status code of the response. default: 200
aliasstringOptional alias of the endpoint.
responseDescriptionstringOptional description of the response.
immutablebooleanOptional flag to indicate if the 'post' endpoint is immutable.
descriptionstringOptional description of the endpoint. Used for openapi.
requestFormatjson,form-data,form-url,binary,textOptional request format of the endpoint. Default is json.
parametersarrayOptional parameters of the endpoint.
errorsarrayOptional errors of the endpoint.

Parameters

The parameters of an endpoint are an array of parameter descriptions. Each parameter description is an object with the following properties:

PropertyTypeDescription
namestringThe name of the parameter.
typePath, Query, Body or HeaderThe type of the parameter.
descriptionstringOptional description of the endpoint. Used for openapi.
schemaZodSchemaThe schema of the parameter using Zod.
Path parameters do not need to be defined in the API definition parameters array.

Indeed, they are automatically deduced from the path and added to the request parameters implicitly. Only declare path parameters in the parameters array if you want to add a description or a schema to validate them

Errors

The errors of an endpoint are an array of error descriptions. Each error description is an object with the following properties:

PropertyTypeDescription
statusnumberThe status code of the error.
descriptionstringOptional description of the error. Used for openapi.
schemaZodSchemaThe schema of the error using Zod.