Verwendung des TypeScript-SDK (@zinn-digital/sdk)

@zinn-digital/sdk ist unser offizieller TypeScript-Client für die Zinn Digital®-API, der auf npm veröffentlicht wird. Jeder Pfad, jeder Parameter und jede Antwort darin wird aus derselben OpenAPI-Spezifikation generiert, auf der die API basiert, und jedes Mal, wenn sich diese Spezifikation ändert, wird automatisch eine neue Version veröffentlicht. Dieser Leitfaden installiert ihn, authentifiziert ihn und führt Ihre ersten Aufrufe durch.

Installieren

npm install @zinn-digital/sdk

Es funktioniert in jeder JavaScript-Laufzeitumgebung, die über fetch verfügt: Node.js, der Browser und Edge-Laufzeitumgebungen. Es hat eine einzige Laufzeitabhängigkeit, openapi-fetch, und ist unter der MIT lizenziert.

Einen API-Schlüssel erstellen

Öffnen Sie die Seite API-Schlüssel Ihres Dashboards (app.zinndigital.com/api-keys) und klicken Sie auf Schlüssel erstellen. Vergeben Sie einen Namen für den Schlüssel und weisen Sie ihm nur die Berechtigungen zu, die Ihr Code benötigt – zum Beispiel sites.view, um Websites aufzulisten. Der Schlüssel wird nur einmal angezeigt; speichern Sie ihn in einer Umgebungsvariable oder Ihrem Secret-Speicher, niemals im Quellcode. Sie können einen Schlüssel jederzeit auf derselben Seite widerrufen.

Öffentliche Katalog-Endpunkte wie Hosting-Regionen und Tarife erfordern keinerlei Schlüssel.

Ihre ersten Aufrufe

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

Führen Sie es mit ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts aus. Die erste Zeile gibt die Hosting-Regionen aus, danach folgt eine Zeile pro Website.

Typen für Ihren eigenen Code

Die Schematypen werden exportiert, sodass Ihre eigenen Funktionen die Strukturen der API verwenden können:

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

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

Ein falsch geschriebener Pfad, Parameter oder ein fehlerhaftes Feld ist ein Kompilierungsfehler und keine Anfrage, die stillschweigend das Falsche tut.

Fehler

Jeder Aufruf gibt { data, error, response } zurück. Bei einer Antwort, die nicht 2xx entspricht, ist data undefiniert und error ist die Fehlerhülle der API: error.error.code, eine für Menschen lesbare error.error.message und bei Validierungsfehlern error.error.details, in denen jedes Feld benannt wird. Ein 403 bedeutet, dass der Schlüssel nicht über die Berechtigung verfügt, die der Endpunkt benötigt – erstellen Sie einen Schlüssel mit dieser Berechtigung, anstatt einen mit umfassenderen Rechten wiederzuverwenden.

Nächste Schritte

• Der Leitfaden auf unserer Website: zinndigital.com/developers/sdk-typescript
• Jeder Endpunkt, seine Parameter und seine Berechtigung: zinndigital.com/developers/api
• Das Paket auf npm: npmjs.com/package/@zinn-digital/sdk