TypeScript SDK (@zinn-digital/sdk) istifadəsi

@zinn-digital/sdk, Zinn Digital® API üçün npm-də dərc olunmuş rəsmi TypeScript müştərimizdir. Buradakı hər bir yol, parametr və cavab API-nin qurulduğu eyni OpenAPI spesifikasiyasından yaradılır və həmin spesifikasiya hər dəfə dəyişdikdə yeni versiya avtomatik olaraq dərc olunur. Bu bələdçi onu quraşdırır, autentifikasiya edir və ilk çağırışlarınızı həyata keçirir.

Quraşdırın

npm install @zinn-digital/sdk

fetch dəstəkləyən istənilən JavaScript icra mühitində işləyir: Node.js, brauzer və edge icra mühitləri. Bir icra asılılığı var, openapi-fetch, və MIT lisenziyalıdır.

API açarı yaradın

İdarəetmə panelinizin API açarları səhifəsini açın (app.zinndigital.com/api-keys) və Açar yaradın düyməsini sıxın. Açara bir ad verin və yalnız kodunuzun ehtiyac duyduğu icazələri təyin edin — məsələn, saytları siyahıya almaq üçün sites.view. Açar yalnız bir dəfə göstərilir; onu mühit dəyişənində və ya məxfi məlumat saxlanclarınızda saxlayın, heç vaxt mənbə kodunda saxlamayın. İstənilən vaxt eyni səhifədə açarı ləğv edə bilərsiniz.

Hostinq bölgələri və planları kimi ictimai kataloq son nöqtələri üçün heç bir açar tələb olunmur.

İlk çağırışlarınız

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);

Bunu ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts ilə işə salın. Birinci sətir hostinq bölgələrini, sonra isə hər sayt üçün bir sətir çap edir.

Öz kodunuz üçün tiplər

Sxem tipləri ixrac olunur, beləliklə öz funksiyalarınız API-nin formalarından istifadə edə bilər:

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

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

Səhv yazılmış yol, parametr və ya sahə səssizcə yanlış iş görən sorğu deyil, kompilyasiya xətasıdır.

Xətalar

Hər bir çağırış { data, error, response } qaytarır. 2xx olmayan cavabda data təyin olunmamışdır (undefined) və error API-nin xəta zərfidir: error.error.code, insanlar tərəfindən oxuna bilən error.error.message və yoxlama uğursuzluqları üçün hər bir sahəni adlandıran error.error.details. 403 açarın son nöqtənin tələb etdiyi icazəyə malik olmadığını bildirir — daha çox icazəsi olanı yenidən istifadə etmək əvəzinə həmin icazəyə malik açar yaradın.

Növbəti addım

• Veb-saytımızdakı bələdçi: zinndigital.com/developers/sdk-typescript
• Hər bir son nöqtə, onun parametrləri və icazəsi: zinndigital.com/developers/api
• npm-dəki paket: npmjs.com/package/@zinn-digital/sdk