Utilisation du SDK TypeScript (@zinn-digital/sdk)

@zinn-digital/sdk est notre client TypeScript officiel pour l’API Zinn Digital®, publié sur npm. Chaque chemin, paramètre et réponse qu’il contient est généré à partir de la même spécification OpenAPI que celle utilisée pour concevoir l’API, et une nouvelle version est publiée automatiquement chaque fois que cette spécification est modifiée. Ce guide permet de l’installer, de l’authentifier et d’effectuer vos premiers appels.

Installer

npm install @zinn-digital/sdk

Il fonctionne dans n’importe quel environnement d’exécution JavaScript disposant de fetch : Node.js, le navigateur et les environnements d’exécution Edge. Il ne comporte qu’une seule dépendance d’exécution, openapi-fetch, et est sous licence MIT.

Créer une clé API

Ouvrez la page Clés API de votre tableau de bord (app.zinndigital.com/api-keys) et appuyez sur Créer une clé. Donnez un nom à la clé et attribuez-lui uniquement les autorisations dont votre code a besoin — par exemple sites.view pour répertorier les sites. La clé n’est affichée qu’une seule fois ; stockez-la dans une variable d’environnement ou dans votre gestionnaire de secrets, jamais dans le code source. Vous pouvez révoquer une clé à tout moment sur cette même page.

Les points de terminaison du catalogue public, tels que les régions d’hébergement et les forfaits, ne nécessitent aucune clé.

Vos premiers appels

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

Exécutez-le avec ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. La première ligne affiche les régions d’hébergement, puis une ligne par site.

Types pour votre propre code

Les types de schéma sont exportés, afin que vos propres fonctions puissent utiliser les structures de l’API :

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

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

Un chemin, un paramètre ou un champ mal orthographié constitue une erreur de compilation plutôt qu’une requête effectuant silencieusement la mauvaise action.

Erreurs

Chaque appel renvoie { data, error, response }. Lors d’une réponse différente de 2xx, data est indéfini et error représente l’enveloppe d’erreur de l’API : error.error.code, un message lisible par l’utilisateur error.error.message et, en cas d’échec de validation, error.error.details indiquant chaque champ. Un code 403 signifie que la clé ne dispose pas de la permission requise par le point de terminaison — créez une clé possédant cette permission plutôt que d’en réutiliser une qui en comporte davantage.

Où aller ensuite

• Le guide sur notre site web : zinndigital.com/developers/sdk-typescript
• Chaque point de terminaison, ses paramètres et sa permission : zinndigital.com/developers/api
• Le paquet sur npm : npmjs.com/package/@zinn-digital/sdk