Использование TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk — это наш официальный клиент TypeScript для API Zinn Digital®, опубликованный в npm. Каждый путь, параметр и ответ в нем создаются на основе той же спецификации OpenAPI, на которой построен API, и новая версия публикуется автоматически при каждом изменении этой спецификации. В этом руководстве рассматривается его установка, аутентификация и выполнение ваших первых вызовов.

Установка

npm install @zinn-digital/sdk

Это работает в любой среде выполнения JavaScript с поддержкой fetch: Node.js, браузере и средах edge. У него есть одна зависимость времени выполнения — openapi-fetch, и оно лицензировано по лицензии MIT.

Создание ключа API

Откройте страницу Ключи API на панели управления (app.zinndigital.com/api-keys) и нажмите Создать ключ. Укажите имя ключа и только те разрешения, которые требуются вашему коду, например sites.view для вывода списка сайтов. Ключ отображается только один раз; сохраните его в переменной окружения или в хранилище секретов, ни в коем случае не в исходном коде. Вы можете отозвать ключ в любое время на этой же странице.

Общедоступные эндпоинты каталога, такие как регионы размещения и тарифные планы, вообще не требуют ключа.

ваши первые вызовы

import { createApiClient } from "@zinn-digital/sdk";

const api = createApiClient({ baseUrl: "https://api.zinndigital.com" });

// Public catalogue endpoints need no key.
const { data: regions } = await api.GET("/v1/catalog/regions");
console.log(regions?.data.map((r) => r.slug));

// Everything else uses a per-organisation API key.
api.use({
  onRequest({ request }) {
    request.headers.set("Authorization", `Bearer ${process.env.ZINN_API_KEY}`);
  },
});

const { data, error } = await api.GET("/v1/sites", { params: { query: { limit: 5 } } });
if (error) throw new Error(error.error.message);
for (const site of data.data) console.log(site.name, site.status);

Запустите с помощью ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. В первой строке выводятся регионы хостинга, затем по одной строке для каждого сайта.

Типы для вашего собственного кода

Типы схем экспортируются, поэтому ваши собственные функции могут использовать структуры API:

import type { components } from "@zinn-digital/sdk";

type Site = components["schemas"]["Site"];
type DnsRecord = components["schemas"]["DnsRecord"];

Неправильно написанный путь, параметр или поле приводит к ошибке компиляции, а не к запросу, который молча выполняет не то действие.

Ошибки

Каждый вызов возвращает { data, error, response }. При ответе, отличном от 2xx, data не определено (undefined), а error представляет собой оболочку ошибки API: error.error.code, понятное человеку сообщение error.error.message и, в случае сбоев валидации, error.error.details с указанием каждого поля. Код 403 означает, что ключ не имеет разрешения, требуемого конечной точкой — создайте ключ с этим разрешением вместо повторного использования ключа с более широкими правами.

Что дальше

• Руководство на нашем сайте: zinndigital.com/developers/sdk-typescript
• Каждая конечная точка, ее параметры и разрешение: zinndigital.com/developers/api
• Пакет на npm: npmjs.com/package/@zinn-digital/sdk