Skip to main content

Getting started

This guide will help you get started with @zimic/http.

Requirements​

Supported environments​

Client side​

@zimic/http is designed to work in any environment that supports the Fetch API. This includes any relatively modern browser. Can I Use is a great resource to check the compatibility of specific features with different browsers.

Server side​

RuntimeVersion
Node.js>= 18.0.0

Supported languages​

TypeScript​

@zimic/http requires TypeScript >= 5.0.

We recommend enabling strict in your tsconfig.json:

tsconfig.json
{
  "compilerOptions": {
    "strict": true
  }
}

JavaScript​

@zimic/http is fully functional on JavaScript, although the type features will be disabled. Consider using TypeScript for improved type safety and developer experience.

Installation​

@zimic/http is available as a library on npm.

npm install @zimic/http --save

We also have canary releases under the tag canary. These have the latest code, including new features, bug fixes, and possibly unstable or breaking changes.

npm install @zimic/http@canary --save

Your first HTTP schema​

Declaring an HTTP schema​

To start using @zimic/http, create an HTTP schema.

The schema represents the structure of your API, including the paths, methods, request and response types.

TIP: OpenAPI Typegen

For APIs with an OpenAPI documentation (e.g. Swagger), the zimic-http typegen CLI can automatically infer the types and generate the schema for you. This is a great way to keep your schema is up to date and save time on manual type definitions.

schema.ts
import { HttpSchema } from '@zimic/http';

interface User {
  username: string;
}

interface RequestError {
  code: string;
  message: string;
}

type Schema = HttpSchema<{
  '/users': {
    POST: {
      request: { body: User };
      response: {
        201: { body: User };
        400: { body: RequestError };
        409: { body: RequestError };
      };
    };

    GET: {
      request: {
        headers: { authorization: string };
        searchParams: {
          query?: string;
          limit?: number;
        };
      };
      response: {
        200: { body: User[] };
        400: { body: RequestError };
        401: { body: RequestError };
      };
    };
  };

  '/users/:userId': {
    PATCH: {
      request: {
        headers: { authorization: string };
        body: Partial<User>;
      };
      response: {
        204: {};
        400: { body: RequestError };
      };
    };
  };
}>;

Next steps​

Guides​

Take a look at our guides for more information on how to use @zimic/http in common scenarios.

Examples​

Try our examples for more practical use cases of @zimic/http with popular libraries and frameworks.

API reference​

Visit the API reference for more details on the resources available in @zimic/http.

Ecosystem​

@zimic/http is a lightweight library that really shines when used with the rest of the ecosystem:

  • @zimic/fetch is a minimal, zero-dependency, and type-safe fetch-like API client. Import your @zimic/http schema to automatically type your paths, methods, requests, parameters, and responses.

  • @zimic/interceptor provides a readable and type-safe way to intercept and mock HTTP requests. Declare realistic HTTP mocks validated with your @zimic/http schema, and verify that your application interacts as expected, without needing to access the actual API.