Korzystanie z TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk to nasz oficjalny klient TypeScript dla API Zinn Digital®, opublikowany w npm. Każda ścieżka, parametr i odpowiedź są w nim generowane na podstawie tej samej specyfikacji OpenAPI, na której zbudowano API, a nowa wersja jest publikowana automatycznie przy każdej zmianie tej specyfikacji. Ten przewodnik przeprowadzi cię przez proces instalacji, uwierzytelniania i wykonywania pierwszych wywołań.

Instalacja

npm install @zinn-digital/sdk

Działa w każdym środowisku uruchomieniowym języka JavaScript, które obsługuje fetch: Node.js, w przeglądarce oraz w środowiskach brzegowych (edge). Posiada jedną zależność czasu wykonywania, openapi-fetch, i jest udostępniane na licencji MIT.

Utwórz klucz API

Proszę otworzyć stronę Klucze API w swoim panelu nawigacyjnym (app.zinndigital.com/api-keys) i nacisnąć Utwórz klucz. Proszę nadać kluczowi nazwę i przyznać wyłącznie te uprawnienia, których wymaga Państwa kod — na przykład sites.view, aby wyświetlać listę witryn. Klucz jest wyświetlany tylko raz; należy zapisać go w zmiennej środowiskowej lub w magazynie wpisów tajnych, nigdy w kodzie źródłowym. Klucz można unieważnić w dowolnym momencie na tej samej stronie.

Publiczne punkty końcowe katalogu, takie jak regiony hostingu i plany, w ogóle nie wymagają klucza.

Państwa pierwsze wywołania

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

Uruchom za pomocą ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Pierwsza linia wyświetla regiony hostingu, a następnie jeden wiersz na każdą witrynę.

Typy dla twojego własnego kodu

Typy schematów są eksportowane, dzięki czemu twoje własne funkcje mogą korzystać ze struktur API:

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

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

Błędnie wpisana ścieżka, parametr lub pole stanowi błąd kompilacji, a nie żądanie, które po cichu wykonuje niewłaściwą operację.

Błędy

Każde wywołanie zwraca { data, error, response }. W przypadku odpowiedzi innej niż 2xx parametr data jest niezdefiniowany, a error to koperta błędu interfejsu API: error.error.code, czytelny dla człowieka komunikat error.error.message oraz, w przypadku błędów walidacji, error.error.details ze wskazaniem każdego pola. Kod 403 oznacza, że klucz nie posiada uprawnienia wymaganego przez dany punkt końcowy — należy utworzyć klucz z tym uprawnieniem, zamiast używać ponownie klucza o szerszych uprawnieniach.

Gdzie przejść dalej

• Przewodnik w naszej witrynie: zinndigital.com/developers/sdk-typescript
• Wszystkie punkty końcowe, ich parametry i uprawnienia: zinndigital.com/developers/api
• Pakiet w npm: npmjs.com/package/@zinn-digital/sdk