Using bodies

Bodies are used to send data in a request and receive data in a response. Request bodies are commonly used to include a payload of data that the server will process, whereas response bodies may contain the result returned by the server. A body can contain various types of data, such as JSON, XML, and binary data such as images and files.

Using request bodies

Request bodies are declared in your schema using the request.body property.

JSON request body

JSON bodies are one of the most common ways to send data in requests. To use a JSON body in a request, declare its type in your schema.

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

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    POST: {
      request: {
        body: { username: string };
      };
      response: {
        201: { body: User };
      };
    };
  };
}>;

Then, use the body option to send the data in your fetch request. Note that you should set the content-type header to application/json to indicate that the body is in JSON format, otherwise it may be interpreted as a plain text. Also, serialize the body with JSON.stringify() before sending it.

import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const response = await fetch('/users', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({ username: 'me' }),
});

TIP: content-type header inference

@zimic/http automatically infers the type of the content-type header as application/json if the request body is a JSON type. You can override this behavior by explicitly setting a different type in your schema.

schema.ts
type Schema = HttpSchema<{
  '/users': {
    POST: {
      request: {
        headers: {
          'content-type': 'application/json; charset=utf-8';
        };
        body: { username: string };
      };
      response: {
        201: { body: User };
      };
    };
  };
}>;

The inference is limited to typing, so you still need to set the header when making requests with JSON bodies. This follows behavior of the Fetch API.

`FormData` request body

FormData is a special type of body to construct a set of key-value pairs with variable types of data. A common use case is to upload files to a server.

To send a FormData body, declare its type in your schema. Use the HttpFormData to indicate that the body is a FormData type.

import { HttpFormData, HttpSchema } from '@zimic/http';

interface AvatarFormDataSchema {
  image: File;
}

type Schema = HttpSchema<{
  '/users/:userId/avatar': {
    PUT: {
      request: {
        headers?: { 'content-type'?: 'multipart/form-data' };
        body: HttpFormData<AvatarFormDataSchema>;
      };
      response: {
        200: { body: { url: string } };
      };
    };
  };
}>;

After that, create an HttpFormData instance and add the data using set or append.

import { HttpFormData } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

// Getting an uploaded file from an input element
const imageInput = document.querySelector<HTMLInputElement>('input[type="file"]');
const imageFile = imageInput!.files![0];

const formData = new HttpFormData<AvatarFormDataSchema>();
formData.append('image', imageFile);

const response = await fetch(`/users/${userId}/avatar`, {
  method: 'PUT',
  headers: { 'content-type': 'multipart/form-data' },
  body: formData,
});

Depending on your runtime, the content-type header may be set automatically when using a FormData body. In that case, you don't need to set it manually.

const response = await fetch(`/users/${userId}/avatar`, {
  method: 'PUT',
  body: formData,
});

Binary request body

Binary bodies are used to send raw binary data in requests. To send a binary body, declare its type in your schema. Blob, ArrayBuffer, and ReadableStream are frequently used types for binary data.

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

interface Video {
  id: string;
  url: string;
}

type Schema = HttpSchema<{
  '/upload': {
    POST: {
      request: {
        headers?: { 'content-type'?: string };
        body: Blob;
      };
    };
    response: {
      201: { body: Video };
    };
  };
}>;

Then, use the body option to send the data in your fetch request. Make sure to set the content-type header, such as video/mp4, image/png, or application/octet-stream for generic binary data. Learn more about MIME types to use in your requests.

import fs from 'fs';
import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

// Getting a file from the file system
const videoBuffer = await fs.promises.readFile('video.mp4');
const videoFile = new File([videoBuffer], 'video.mp4');

const response = await fetch('/upload', {
  method: 'POST',
  headers?: { 'content-type'?: 'video/mp4' },
  body: videoFile,
});

If you want to stream the request body, use ReadableStream to create a stream of data. This is useful for large files or when you want to send data in chunks.

type Schema = HttpSchema<{
  '/upload': {
    POST: {
      request: {
        headers?: { 'content-type'?: string };
        body: ReadableStream;
      };
    };
    response: {
      201: { body: Video };
    };
  };
}>;

import fs from 'fs';
import { Readable } from 'stream';

const videoStream = fs.createReadStream('video.mp4');

const response = await fetch('/upload', {
  method: 'POST',
  headers?: { 'content-type'?: 'video/mp4' },
  body: Readable.toWeb(videoStream) as ReadableStream,
});

Plain-text request body

Plain-text bodies can be declared as a string.

import { HttpSchema } from '@zimic/http';

type Schema = HttpSchema<{
  '/content': {
    POST: {
      request: {
        body: string;
      };
      response: {
        201: {};
      };
    };
  };
}>;

After that, send a plain-text body as a string in your fetch request.

const response = await fetch('/content', {
  method: 'POST',
  body: 'text',
});

URL-encoded request body

Bodies with URL-encoded data can be declared with HttpSearchParams.

import { HttpSchema, HttpSearchParams } from '@zimic/http';

interface UserCreationSearchParams {
  username: string;
}

type Schema = HttpSchema<{
  '/users': {
    POST: {
      request: {
        headers?: { 'content-type'?: 'application/x-www-form-urlencoded' };
        body: HttpSearchParams<UserCreationSearchParams>;
      };
    };
  };
}>;

Then, use the body option to send the data in your fetch request. The HttpSearchParams type will be automatically serialized to a URL-encoded string, and the content-type header will be set to application/x-www-form-urlencoded.

import { HttpSearchParams } from '@zimic/http';
import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const searchParams = new HttpSearchParams<UserCreationSearchParams>({
  username: 'me',
});

const response = await fetch('/users', {
  method: 'POST',
  body: searchParams,
});

Using response bodies

Response bodies are declared in your schema using the response.<status>.body property.

JSON response body

To receive a JSON response body, declare its type in your schema.

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

interface User {
  id: string;
  username: string;
}

type Schema = HttpSchema<{
  '/users/:userId': {
    GET: {
      response: {
        200: {
          body: User;
        };
      };
    };
  };
}>;

Then, use response.json() to parse the response body as JSON. The result is automatically typed according to your schema.

import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const response = await fetch('/users/1', {
  method: 'GET',
});

const user = await response.json();

`FormData` response body

To receive a FormData response body, declare its type in your schema. Use the HttpFormData to indicate that the body is a FormData type.

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

interface AvatarFormDataSchema {
  image: File;
}

type Schema = HttpSchema<{
  '/users/:userId/avatar': {
    GET: {
      response: {
        200: {
          headers?: { 'content-type'?: 'multipart/form-data' };
          body: HttpFormData<AvatarFormDataSchema>;
        };
      };
    };
  };
}>;

Then, use response.formData() to parse the response body as FormData. The result is automatically typed according to your schema.

import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const response = await fetch(`/users/${user.id}/avatar`, {
  method: 'GET',
});

const formData = await response.formData();

Binary response body

To receive a binary response body, declare its type in your schema.

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

interface Video {
  id: string;
  url: string;
}

type Schema = HttpSchema<{
  '/videos/:videoId': {
    GET: {
      response: {
        200: {
          headers?: { 'content-type'?: string };
          body: Blob;
        };
      };
    };
  };
}>;

Then, use response.blob() or response.arrayBuffer() to parse the response body as binary data.

import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const response = await fetch(`/videos/${video.id}`, {
  method: 'GET',
});

const videoBlob = await response.blob();

If you need streaming, you can use response.body to get a ReadableStream. This is useful for large files, when you want to process the data in chunks, or when you want to pipe the data to another stream, such as a local file.

import fs from 'fs';
import stream, { Readable } from 'stream';
import { ReadableStream as NodeReadableStream } from 'stream/web';

const response = await fetch(`/videos/${video.id}`, {
  method: 'GET',
});

const videoStream = Readable.fromWeb(response.body as NodeReadableStream);
const outputStream = fs.createWriteStream('video.mp4');

// Stream the response body to a file
await stream.promises.pipeline(videoStream, outputStream);

Plain-text response body

To receive a plain-text response body, declare its type in your schema.

schema.ts
import { HttpSchema } from '@zimic/http';
type Schema = HttpSchema<{
  '/content': {
    GET: {
      response: {
        200: {
          body: string;
        };
      };
    };
  };
}>;

Then, use response.text() to parse the response body as plain text.

import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const response = await fetch('/content', {
  method: 'GET',
});

const content = await response.text();

URL-encoded response body

To receive a URL-encoded response body, declare its type in your schema. Use the HttpSearchParams to indicate that the body is a URL-encoded type.

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

type Schema = HttpSchema<{
  '/users': {
    GET: {
      response: {
        200: {
          headers?: { 'content-type'?: 'application/x-www-form-urlencoded' };
          body: HttpSearchParams<{ username: string }>;
        };
      };
    };
  };
}>;

Then, use response.formData() to parse the response body as URL-encoded data. The result is automatically typed according to your schema.

import { createFetch } from '@zimic/fetch';

const fetch = createFetch<Schema>({
  baseURL: 'http://localhost:3000',
});

const response = await fetch('/users', {
  method: 'GET',
});

const searchParams = await response.formData();

Using request bodies​

JSON request body​

FormData request body​

Binary request body​

Plain-text request body​

URL-encoded request body​

Using response bodies​

JSON response body​

FormData response body​

Binary response body​

Plain-text response body​

URL-encoded response body​