A TypeScript SDK (@zinn-digital/sdk) használata

A @zinn-digital/sdk a hivatalos TypeScript-kliensünk a Zinn Digital® API-hoz, amelyet az npm felületén tettünk közzé. A benne található minden útvonal, paraméter és válasz ugyanabból az OpenAPI-specifikációból jön létre, amelyből maga az API is felépül, és automatikusan új verzió jelenik meg, valahányszor ez a specifikáció módosul. Ez az útmutató bemutatja a telepítését, a hitelesítését és az első hívások kezdeményezését.

Telepítés

npm install @zinn-digital/sdk

Minden olyan JavaScript-futtatókörnyezetben működik, amely rendelkezik a fetch funkcióval: Node.js, a böngésző és az edge-futtatókörnyezetek. Egyetlen futásidejű függősége van, az openapi-fetch, és MIT-licenccel rendelkezik.

API-kulcs létrehozása

Nyissa meg az irányítópult API-kulcsok oldalát (app.zinndigital.com/api-keys), majd nyomja meg a Kulcs létrehozása gombot. Adjon nevet a kulcsnak, és csak azokat az engedélyeket rendelje hozzá, amelyekre a kódjának szüksége van — például sites.view a webhelyek listázásához. A kulcs csak egyszer jelenik meg; tárolja egy környezeti változóban vagy a titkos kulcstárban, soha ne a forráskódban. Bármikor visszavonhatja a kulcsot ugyanezen az oldalon.

A nyilvános katalógus-végpontokhoz, például a tárhelyrégiókhoz és a csomagokhoz egyáltalán nincs szükség kulcsra.

Az első hívásai

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

Futtassa a ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts paranccsal. Az első sor a tárhelyrégiókat írja ki, majd webhelyenként egy-egy sort.

Típusok a saját kódjához

A sématípusok exportálva vannak, így a saját függvényei is használhatják az API struktúráit:

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

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

Az elgépelt útvonal, paraméter vagy mező fordítási hibát eredményez, ahelyett hogy kérésként észrevétlenül hibás műveletet hajtana végre.

Hibák

Minden hívás a következővel tér vissza: { data, error, response }. Nem 2xx válasz esetén a data értéke definiálatlan, az error pedig az API hibaobjektuma: error.error.code, egy ember által olvasható error.error.message, valamint érvényesítési hibák esetén az egyes mezőket megnevező error.error.details. A 403 azt jelenti, hogy a kulcs nem rendelkezik a végpont által megkövetelt engedéllyel — hozzon létre egy ilyen engedéllyel rendelkező kulcsot ahelyett, hogy egy bővebb jogosultságút használna fel újra.

Merre tovább?

• Útmutató a weboldalunkon: zinndigital.com/developers/sdk-typescript
• Minden végpont, azok paraméterei és engedélyei: zinndigital.com/developers/api
• A csomag az npm felületén: npmjs.com/package/@zinn-digital/sdk