Upotreba TypeScript SDK-a (@zinn-digital/sdk)

@zinn-digital/sdk naš je službeni TypeScript klijent za Zinn Digital® API, objavljen na npm-u. Svaka staza, parametar i odgovor u njemu generirani su iz iste OpenAPI specifikacije iz koje je izgrađen i sam API, a nova se verzija objavljuje automatski kad god se ta specifikacija promijeni. Ovaj vodič ga instalira, autentificira i upućuje Vaše prve pozive.

Instalacija

npm install @zinn-digital/sdk

Radi u svakom JavaScript izvođenju koje ima fetch: Node.js, preglednik i rubna izvođenja (edge runtimes). Ima jednu zavisnost pri izvođenju, openapi-fetch, i licenciran je pod MIT licencom.

Stvorite API ključ

Otvorite stranicu API ključevi na svojoj nadzornoj ploči (app.zinndigital.com/api-keys) i pritisnite Stvori ključ. Dodijelite ključu naziv i samo one dozvole koje su potrebne vašem kodu — na primjer sites.view za popis web-mjesta. Ključ se prikazuje samo jednom; pohranite ga u varijablu okruženja ili u svoju sigurnu pohranu tajni, nikada u izvorni kod. Ključ možete opozvati u bilo kojem trenutku na istoj stranici.

Javne krajnje točke kataloga, poput regija hostinga i planova, uopće ne zahtijevaju ključ.

Vaši prvi pozivi

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

Pokrenite ga pomoću ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Prvi redak ispisuje regije hostinga, a zatim jedan redak po web-mjestu.

Tipovi za vaš vlastiti kôd

Tipovi sheme se izvoze, tako da vaše vlastite funkcije mogu koristiti oblike API-ja:

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

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

Pogrešno napisana putanja, parametar ili polje predstavljaju pogrešku pri prevođenju, a ne zahtjev koji tiho izvršava pogrešnu radnju.

Pogreške

Svaki poziv vraća { data, error, response }. Pri odgovoru koji nije 2xx, data je nedefiniran, a error je omotnica pogreške API-ja: error.error.code, ljudima čitljiva poruka error.error.message te, u slučaju neuspjele provjere valjanosti, error.error.details s navedenim svakim poljem. 403 znači da ključ ne sadrži dopuštenje koje krajnja točka zahtijeva — stvorite ključ s tim dopuštenjem umjesto ponovne upotrebe onoga s više ovlasti.

Kamo dalje

• Vodič na našem web-mjestu: zinndigital.com/developers/sdk-typescript
• Svaka krajnja točka, njezini parametri i njezino dopuštenje: zinndigital.com/developers/api
• Paket na servisu npm: npmjs.com/package/@zinn-digital/sdk