Коришћење 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