@matchi/api

MATCHi API Client

Introduction

This is the MATCHi API client for JavaScript and TypeScript. It is generated from the OpenAPI specification and is intended to be used when building applications that integrates with the MATCHi API.

Installation

npm install @matchi/api # using npm
yarn add @matchi/api # using yarn
bun install @matchi/api # using bun

Get started

import { OpenAPI } from "@matchi/api";

OpenAPI.BASE = MATCHI_API_URL;
OpenAPI.HEADERS = { "x-api-key": MATCHI_API_KEY };

// To use the authenticated endpoints
// set the access token
OpenAPI.TOKEN = MATCHI_ACCESS_TOKEN;

// You can also use a promise to set the access token
const getValidAccessToken = async () => {
  // Get a valid access token
  return MATCHI_ACCESS_TOKEN;
};
OpenAPI.TOKEN = getValidAccessToken;

Usage

Basic usage

// Once you've got the dependency locally, you can inspect the exports to
// see what's available.

// The classes that ends in "Service" are entrypoints for making HTTP calls.
import { AnonymousService } from "@matchi/api";

try {
  // fetch() is used as the underlying HTTP client
  const activities = await AnonymousService.listActivities();
} catch (error) {
  // Handle error
}

Custom timeout

import { AnonymousService } from "@matchi/api";

try {
  // Create a promise that will fetch the activities
  const promise = AnonymousService.listActivities();

  const timeoutId = setTimeout(() => {
    // If the promise hasn't resolved within 1 second, cancel it
    promise.cancel();

    // Throw an error to indicate that the request timed out
    throw new Error("Timeout");
  }, 1000);

  // Wait for the promise to resolve
  const activities = await promise;

  // Clear the timeout, since the promise resolved within 1 second
  clearTimeout(timeoutId);

  return activities;
} catch (error) {
  // Handle error
}

Local version

To run the client generation locally, targeting your local backend, you can run the following command.

BACKEND_REPO=../matchi-backend  bun run build-local

This in turn relies on your checked out backend to have generated the specification required. (Which can be done with BACKEND_REPO=../matchi-backend make -C ${BACKEND_REPO}/infra/matchiapi generate-spec.)

Having a client for a local backend can be useful any time when you want a client for a backend which is not yet merged to the matchi-backend main.