Përdorimi i TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk është klienti ynë zyrtar TypeScript për Zinn Digital® API, i publikuar në npm. Çdo shteg, parametër dhe përgjigje në të gjenerohet nga i njëjti specifikim OpenAPI mbi të cilin është ndërtuar API-ja, dhe një version i ri publikohet automatikisht sa herë që ai specifikim ndryshon. Ky udhëzues e instalon atë, bën autentikimin e tij dhe kryen thirrjet tuaja të para.

Instalimi

npm install @zinn-digital/sdk

Funksionon në çdo mjedis ekzekutimi JavaScript që ka fetch: Node.js, shfletues dhe mjedise edge. Ka një varësi ekzekutimi, openapi-fetch, dhe është i licencuar me MIT.

Krijoni një çelës API

Hapni faqen Çelësat API të panelit tuaj (app.zinndigital.com/api-keys) dhe shtypni Krijoni një çelës. Vendosini çelësit një emër dhe vetëm lejet që i nevojiten kodit tuaj — për shembull sites.view për të listuar faqet. Çelësi shfaqet vetëm një herë; ruajeni atë në një variabël mjedisi ose në ruajtësin tuaj të sekreteve, kurrë në kodin burimor. Mund ta revokoni një çelës në çdo kohë në po të njëjtën faqe.

Pikat fundore të katalogut publik, të tilla si rajonet e pritjes dhe planet, nuk kërkojnë fare çelës.

Thirrjet tuaja të para

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

Ekzekutojeni me ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Rreshti i parë shfaq rajonet e pritjes, më pas një rresht për çdo faqe.

Llojet për kodin tuaj

Llojet e skemës eksportohen, kështu që funksionet tuaja mund të përdorin format e API-së:

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

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

Një shteg, parametër ose fushë e shkruar gabim është një gabim kompilimi dhe jo një kërkesë që bën gabimisht diçka në heshtje.

Gabimet

Çdo thirrje kthen { data, error, response }. Në një përgjigje jo-2xx data është e papërcaktuar dhe error është mbështjellësi i gabimit të API-së: error.error.code, një error.error.message i lexueshëm nga njeriu dhe, për dështimet e vlefshmërisë, error.error.details që emërton secilën fushë. Një 403 do të thotë se çelësi nuk mbart lejen që i nevojitet pikës fundore — krijoni një çelës me atë leje në vend që të ripërdorni një me më shumë leje.

Ku të shkoni më pas

• Udhëzuesi në faqen tonë të internetit: zinndigital.com/developers/sdk-typescript
• Çdo pikë fundore, parametrat e saj dhe leja e saj: zinndigital.com/developers/api
• Paketa në npm: npmjs.com/package/@zinn-digital/sdk