Utilizzo dell'SDK TypeScript (@zinn-digital/sdk)

@zinn-digital/sdk è il nostro client TypeScript ufficiale per l'API di Zinn Digital®, pubblicato su npm. Ogni percorso, parametro e risposta al suo interno viene generato dalla stessa specifica OpenAPI su cui è creata l'API, e una nuova versione viene pubblicata automaticamente ogni volta che tale specifica subisce modifiche. Questa guida illustra come installarlo, autenticarlo ed eseguire le prime chiamate.

Installa

npm install @zinn-digital/sdk

Funziona in qualsiasi runtime JavaScript dotato di fetch: Node.js, il browser e i runtime edge. Presenta una sola dipendenza di runtime, openapi-fetch, ed è con licenza MIT.

Crea una chiave API

Apra la pagina Chiavi API della Sua bacheca (app.zinndigital.com/api-keys) e prema Crea una chiave. Assegni un nome alla chiave e soltanto le autorizzazioni necessarie al Suo codice, ad esempio sites.view per visualizzare l'elenco dei siti. La chiave viene mostrata una sola volta; la memorizzi in una variabile di ambiente o nel Suo archivio di segreti, mai nel codice sorgente. Può revocare una chiave in qualsiasi momento dalla stessa pagina.

Gli endpoint pubblici del catalogo, come le aree geografiche di hosting e i piani, non richiedono alcuna chiave.

Le Sue prime chiamate

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

Eseguitelo con ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. La prima riga stampa le regioni di hosting, quindi una riga per sito.

Tipi per il Vostro codice

I tipi dello schema vengono esportati, in modo che le Vostre funzioni possano utilizzare le forme dell'API:

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

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

Un percorso, un parametro o un campo con errori di battitura rappresenta un errore di compilazione anziché una richiesta che esegue silenziosamente l'operazione sbagliata.

Errori

Ogni chiamata restituisce { data, error, response }. In caso di risposta non 2xx, data è undefined ed error rappresenta la struttura di errore dell'API: error.error.code, un messaggio leggibile error.error.message e, per gli errori di convalida, error.error.details che specifica ogni campo. Un 403 indica che la chiave non dispone dell'autorizzazione richiesta dall'endpoint; crei una chiave con tale autorizzazione anziché riutilizzarne una con privilegi maggiori.

Passaggi successivi

• La guida sul nostro sito web: zinndigital.com/developers/sdk-typescript
• Ciascun endpoint, i relativi parametri e la relativa autorizzazione: zinndigital.com/developers/api
• Il pacchetto su npm: npmjs.com/package/@zinn-digital/sdk