Použití TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk je náš oficiální TypeScript klient pro Zinn Digital® API, publikovaný na npm. Každá cesta, parametr i odpověď jsou v něm generovány ze stejné specifikace OpenAPI, na které je API postaveno, a nová verze je automaticky publikována při každé změně této specifikace. Tato příručka vám pomůže jej nainstalovat, autentizovat a provést vaše první volání.

Instalace

npm install @zinn-digital/sdk

Funguje v libovolném běhovém prostředí JavaScriptu, které obsahuje fetch: Node.js, prohlížeč a edge běhová prostředí. Má jednu závislost za běhu, openapi-fetch, a je pod licencí MIT.

Vytvořit klíč API

Otevřete stránku Klíče API na svém řídicím panelu (app.zinndigital.com/api-keys) a stiskněte Vytvořit klíč. Pojmenujte klíč a přiřaďte mu pouze oprávnění, která váš kód potřebuje — například sites.view pro zobrazení seznamu webů. Klíč se zobrazí pouze jednou; uložte jej do proměnné prostředí nebo do úložiště tajných klíčů, nikdy do zdrojového kódu. Klíč můžete kdykoli odvolat na stejné stránce.

Veřejné koncové body katalogu, jako jsou hostingové regiony a plány, nepotřebují vůbec žádný klíč.

Vaše první volání

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

Spusťte jej pomocí ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. První řádek vypíše hostingové regiony, poté jeden řádek pro každý web.

Typy pro váš vlastní kód

Typy schémat jsou exportovány, takže vaše vlastní funkce mohou používat tvary rozhraní API:

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

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

Chybně zapsaná cesta, parametr nebo pole je chybou při kompilaci, nikoli požadavkem, který v tichosti provede nesprávnou akci.

Chyby

Každé volání vrací { data, error, response }. Při jiné odpovědi než 2xx je data nedefinováno (undefined) a error představuje obálku chyby API: error.error.code, lidsky čitelné error.error.message a v případě neúspěšné validace error.error.details uvádějící jednotlivá pole. Hodnota 403 znamená, že klíč neobsahuje oprávnění, které koncový bod vyžaduje — vytvořte klíč s tímto oprávněním, než abyste opakovaně používali klíč s širšími právy.

Kam dál

• Průvodce na našem webu: zinndigital.com/developers/sdk-typescript
• Každý koncový bod, jeho parametry a jeho oprávnění: zinndigital.com/developers/api
• Balíček na npm: npmjs.com/package/@zinn-digital/sdk