TypeScript SDK (@zinn-digital/sdk) Kullanımı

@zinn-digital/sdk, npm üzerinde yayımlanan Zinn Digital® API'si için resmi TypeScript istemcimizdir. İçindeki her yol, parametre ve yanıt, API'nin oluşturulduğu aynı OpenAPI spesifikasyonundan üretilir ve bu spesifikasyon her değiştiğinde otomatik olarak yeni bir sürüm yayımlanır. Bu kılavuz onu yükler, kimliğini doğrular ve ilk çağrılarınızı gerçekleştirir.

Yükle

npm install @zinn-digital/sdk

Node.js, tarayıcı ve edge çalışma zamanları gibi fetch özelliğine sahip her JavaScript çalışma zamanında çalışır. openapi-fetch olmak üzere tek bir çalışma zamanı bağımlılığına sahiptir ve MIT lisanslıdır.

API anahtarı oluşturma

Kontrol panelinizin API anahtarları sayfasını (app.zinndigital.com/api-keys) açın ve Bir anahtar oluştur seçeneğine basın. Anahtara bir ad verin ve yalnızca kodunuzun ihtiyaç duyduğu izinleri tanımlayın; örneğin, siteleri listelemek için sites.view. Anahtar yalnızca bir kez gösterilir; onu asla kaynak kodunda değil, bir ortam değişkeninde veya gizli bilgi deponuzda saklayın. Bir anahtarı dilediğiniz zaman aynı sayfadan iptal edebilirsiniz.

Barındırma bölgeleri ve planları gibi herkese açık katalog uç noktaları için hiçbir anahtar gerekmez.

İlk çağrılarınız

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

ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts komutuyla çalıştırın. İlk satır barındırma bölgelerini, ardından her site için bir satır yazdırır.

Kendi kodunuz için türler

Şema türleri dışa aktarılmıştır, böylece kendi işlevleriniz API'nin biçimlerini kullanabilir:

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

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

Yanlış yazılmış bir yol, parametre veya alan; sessizce yanlış işlem yapan bir istek yerine derleme hatası olarak değerlendirilir.

Hatalar

Her çağrı { data, error, response } döndürür. 2xx dışındaki bir yanıtta data tanımsızdır ve error API'nin hata zarfıdır: error.error.code, insanlar tarafından okunabilir bir error.error.message ve doğrulama hataları için her alanı belirten error.error.details. 403, anahtarın uç noktanın gerektirdiği izni taşımadığı anlamına gelir; daha fazla izne sahip bir anahtarı yeniden kullanmak yerine bu izne sahip bir anahtar oluşturun.

Sırada ne var

• Web sitemizdeki rehber: zinndigital.com/developers/sdk-typescript
• Her uç nokta, parametreleri ve izni: zinndigital.com/developers/api
• npm üzerindeki paket: npmjs.com/package/@zinn-digital/sdk