Използване на 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 е недефинирана (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