استفاده از TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk کلاینت رسمی TypeScript ما برای Zinn Digital® API است که در npm منتشر شده است. هر مسیر، پارامتر و پاسخ در آن از همان مشخصات OpenAPI تولید می‌شود که API از آن ساخته شده است، و هر بار که این مشخصات تغییر کند، نسخه جدیدی به‌طور خودکار منتشر می‌شود. این راهنما آن را نصب می‌کند، احراز هویت می‌کند و اولین فراخوانی‌های شما را انجام می‌دهد.

نصب

npm install @zinn-digital/sdk

در هر محیط زمان اجرای JavaScript که دارای fetch باشد کار می‌کند: Node.js، مرورگر و محیط‌های زمان اجرای edge. این ابزار دارای یک وابستگی زمان اجرا به نام openapi-fetch است و تحت مجوز MIT قرار دارد.

ایجاد یک کلید API

صفحه کلیدهای API داشبورد خود را باز کنید (app.zinndigital.com/api-keys) و ایجاد یک کلید را فشار دهید. یک نام به کلید بدهید و فقط مجوزهایی را تعیین کنید که کد شما به آنها نیاز دارد — برای مثال sites.view جهت فهرست کردن سایت‌ها. کلید فقط یک بار نشان داده می‌شود؛ آن را در یک متغیر محیطی یا مخزن اسرار خود ذخیره کنید، هرگز در کد منبع قرار ندهید. شما می‌توانید در هر زمان یک کلید را در همان صفحه لغو کنید.

نقاط پایانی کاتالوگ عمومی، مانند مناطق میزبانی و طرح‌ها، اصلاً به هیچ کلیدی نیاز ندارند.

نخستین فراخوانی‌های شما

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 اجرا کنید. خط اول مناطق میزبانی را چاپ می‌کند، سپس یک خط برای هر سایت.

انواع داده برای کد خودتان

انواع شِما صادر می‌شوند، بنابراین توابع خودتان می‌توانند از ساختارهای API استفاده کنند:

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

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

یک مسیر، پارامتر یا فیلد که اشتباه تایپ شده باشد، به‌جای درخواستی که در سکوت کار اشتباهی را انجام دهد، یک خطای کامپایل است.

خطاها

هر فراخوانی { data, error, response } را برمی‌گرداند. در یک پاسخ غیر از 2xx مقدار data تعریف‌نشده (undefined) است و error همان پوشش خطای API است: error.error.code، یک error.error.message خوانا برای انسان، و برای موارد عدم موفقیت در اعتبارسنجی، error.error.details که نام هر فیلد را مشخص می‌کند. کد 403 بدان معناست که کلید فاقد مجوزی است که نقطه پایانی نیاز دارد — به‌جای استفاده مجدد از کلیدی با مجوزهای بیشتر، کلیدی با همان مجوز ایجاد کنید.

مراحل بعدی

• راهنمای موجود در وب‌سایت ما: zinndigital.com/developers/sdk-typescript
• تمام نقاط پایانی، پارامترهای آن‌ها و مجوز مربوطه: zinndigital.com/developers/api
• بسته در npm: npmjs.com/package/@zinn-digital/sdk