Використання TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk — це наш офіційний клієнт TypeScript для Zinn Digital® API, опублікований на 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 не визначено, а 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