Utilizarea TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk este clientul nostru oficial TypeScript pentru API-ul Zinn Digital®, publicat pe npm. Fiecare cale, parametru și răspuns din acesta este generat din aceeași specificație OpenAPI pe baza căreia este construit API-ul, iar o nouă versiune este publicată automat ori de câte ori această specificație se modifică. Acest ghid îl instalează, îl autentifică și efectuează primele dumneavoastră apeluri.

Instalare

npm install @zinn-digital/sdk

Funcționează în orice mediu de execuție JavaScript care dispune de fetch: Node.js, browserul și mediile edge. Are o singură dependență de execuție, openapi-fetch, și este licențiat MIT.

Creați o cheie API

Deschideți pagina Chei API din tabloul dumneavoastră de bord (app.zinndigital.com/api-keys) și apăsați pe Creați o cheie. Dați un nume cheii și acordați doar permisiunile de care are nevoie codul dumneavoastră — de exemplu sites.view pentru a lista site-urile. Cheia este afișată o singură dată; stocați-o într-o variabilă de mediu sau în magazinul dumneavoastră de secrete, niciodată în codul sursă. Puteți revoca o cheie în orice moment pe aceeași pagină.

Punctele finale publice ale catalogului, cum ar fi regiunile de găzduire și planurile, nu necesită nicio cheie.

Primele dumneavoastră apeluri

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

Rulați cu ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Prima linie afișează regiunile de găzduire, apoi câte o linie pentru fiecare site.

Tipuri pentru propriul dumneavoastră cod

Tipurile de schemă sunt exportate, astfel încât propriile dumneavoastră funcții pot folosi formatele API-ului:

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

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

O cale, un parametru sau un câmp scris greșit reprezintă o eroare de compilare, mai degrabă decât o solicitare care execută în mod silențios o acțiune incorectă.

Erori

Fiecare apel returnează { data, error, response }. În cazul unui răspuns diferit de 2xx, data este nedefinit, iar error reprezintă anvelopa de eroare a API-ului: error.error.code, un mesaj ușor de citit de către oameni error.error.message și, pentru eșecurile de validare, error.error.details care indică fiecare câmp. O eroare 403 înseamnă că cheia nu include permisiunea necesară pentru punctul final — creați o cheie cu acea permisiune în loc să reutilizați una cu mai multe permisiuni.

Pașii următori

• Ghidul de pe site-ul nostru web: zinndigital.com/developers/sdk-typescript
• Fiecare punct final, parametrii și permisiunea acestuia: zinndigital.com/developers/api
• Pachetul de pe npm: npmjs.com/package/@zinn-digital/sdk