De TypeScript SDK (@zinn-digital/sdk) gebruiken

@zinn-digital/sdk is onze officiële TypeScript-client voor de Zinn Digital®-API, gepubliceerd op npm. Elk pad, elke parameter en elke respons hierin is gegenereerd op basis van dezelfde OpenAPI-specificatie waarop de API is gebouwd, en er wordt automatisch een nieuwe versie gepubliceerd wanneer die specificatie verandert. Deze handleiding installeert het, verifieert het en voert uw eerste aanroepen uit.

Installeren

npm install @zinn-digital/sdk

Het werkt in elke JavaScript-runtime die beschikt over fetch: Node.js, de browser en edge-runtimes. Het heeft één runtime-afhankelijkheid, openapi-fetch, en is uitgebracht onder de MIT-licentie.

Een API-sleutel maken

Open de pagina API-sleutels van uw dashboard (app.zinndigital.com/api-keys) en druk op Een sleutel maken. Geef de sleutel een naam en verleen alleen de rechten die uw code nodig heeft — bijvoorbeeld sites.view om sites weer te geven. De sleutel wordt eenmalig getoond; bewaar deze in een omgevingsvariabele of in uw geheime opslag, nooit in de broncode. U kunt een sleutel op elk moment intrekken op dezelfde pagina.

Openbare catalogus-eindpunten, zoals hostingregio's en -pakketten, hebben helemaal geen sleutel nodig.

Uw eerste oproepen

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

Voer het uit met ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. De eerste regel toont de hostingregio's, gevolgd door één regel per site.

Types voor uw eigen code

De schematypes worden geëxporteerd, zodat uw eigen functies de API-vormen kunnen gebruiken:

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

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

Een verkeerd gespeld pad, parameter of veld is een compilatiefout in plaats van een verzoek dat stilletjes het verkeerde doet.

Fouten

Elke aanroep retourneert { data, error, response }. Bij een niet-2xx-respons is data undefined en is error de foutenvelope van de API: error.error.code, een voor mensen leesbare error.error.message en, bij validatiefouten, error.error.details waarin elk veld wordt genoemd. Een 403 betekent dat de sleutel niet over de rechten beschikt die het eindpunt nodig heeft — maak een sleutel aan met die rechten in plaats van een sleutel met meer rechten te hergebruiken.

Waar u vervolgens heen kunt gaan

• De handleiding op onze website: zinndigital.com/developers/sdk-typescript
• Elk eindpunt, de bijbehorende parameters en de bijbehorende rechten: zinndigital.com/developers/api
• Het pakket op npm: npmjs.com/package/@zinn-digital/sdk