Skip to main content

BuildApiClient

The buildApiClient function creates a type-safe API client by combining a request factory and an API specification.

Syntax​

import { ApiSpec } from '@api-ts/io-ts-http';

function buildApiClient<T extends ApiSpec>(
  requestFactory: RequestFactory,
  apiSpec: T,
): ApiClient<T>;

// Types used by buildApiClient
type RequestFactory = (method: string, path: string, options?: any) => any; // Returns a superagent/supertest request

// ApiClient structure based on the input ApiSpec 'T'
type ApiClient<T extends ApiSpec> = {
  [OperationName in keyof T]: {
    [MethodName in keyof T[OperationName]]: (
      props: any, // Inferred from T[OperationName][MethodName]['request']
    ) => PreparedRequest<T[OperationName][MethodName]>;
  };
};

// Response types
type ApiResponse<RouteDef> = {
  status: number;
  body: any;
  // Additional properties from the response
};

type SpecificApiResponse<RouteDef, Status extends number> = {
  status: Status;
  body: any;
  // Additional properties from the response
};

// Object returned before executing the request
type PreparedRequest<RouteDef> = {
  decode: () => Promise<ApiResponse<RouteDef>>;
  decodeExpecting: (status: number) => Promise<SpecificApiResponse<RouteDef, number>>;
};

Parameters​

  • requestFactory: A function that creates HTTP requests.

    • Type: RequestFactory
    • Source: Returned by superagentRequestFactory or supertestRequestFactory.

  • apiSpec: An object that defines the API structure, routes, requests, and responses.

    • Type: ApiSpec
    • Source: Created using @api-ts/io-ts-http's apiSpec function.

Return Value​

  • A strongly-typed object representing the API client.

Example​

import { superagentRequestFactory, buildApiClient } from '@api-ts/superagent-wrapper';
import * as superagent from 'superagent';
import { apiSpec } from './my-api-spec';

// Create a request factory
const requestFactory = superagentRequestFactory(
  superagent,
  'https://api.example.com/v1',
);

// Build the API client
const apiClient = buildApiClient(requestFactory, apiSpec);

// Use the client to make type-safe API calls
const response = await apiClient.users.get({ id: 123 }).decode();