TypeScript SDK (@zinn-digital/sdk) کا استعمال

@zinn-digital/sdk Zinn Digital® API کے لیے ہمارا باضابطہ TypeScript کلائنٹ ہے، جو npm پر شائع کیا گیا ہے۔ اس میں موجود ہر پاتھ، پیرامیٹر اور جواب اسی OpenAPI تفصیلات سے تیار کیا جاتا ہے جس سے API بنایا گیا ہے، اور جب بھی اس تفصیلات میں تبدیلی ہوتی ہے تو خودکار طور پر ایک نیا ورژن شائع ہو جاتا ہے۔ یہ گائیڈ اسے انسٹال کرتی ہے، اس کی تصدیق کرتی ہے اور آپ کی پہلی کالز کرتی ہے۔

انسٹال کریں

npm install @zinn-digital/sdk

یہ fetch کی سہولت رکھنے والے کسی بھی JavaScript رن ٹائم میں کام کرتا ہے: Node.js، براؤزر اور ایج رن ٹائمز۔ اس کا ایک رن ٹائم انحصار openapi-fetch ہے، اور یہ MIT کے تحت لائسنس یافتہ ہے۔

ایک API کلید بنائیں

اپنے ڈیش بورڈ کا API کلیدیں والا صفحہ (app.zinndigital.com/api-keys) کھولیں اور ایک کلید بنائیں دبائیں۔ کلید کو ایک نام دیں اور صرف وہی اجازتیں دیں جن کی آپ کے کوڈ کو ضرورت ہے — مثال کے طور پر سائٹس کی فہرست دیکھنے کے لیے sites.view۔ کلید صرف ایک بار دکھائی جاتی ہے؛ اسے کسی ماحولیاتی متغیر (environment variable) یا اپنے خفیہ اسٹور میں محفوظ کریں، سورس کوڈ میں کبھی نہیں۔ آپ اسی صفحے پر کسی بھی وقت کلید منسوخ کر سکتے ہیں۔

عوامی کیٹلاگ اینڈ پوائنٹس، جیسے ہوسٹنگ کے خطے اور منصوبے، کو کسی کلید کی بالکل ضرورت نہیں ہوتی ہے۔

آپ کی پہلی کالز

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 غیر متعین ہوتا ہے اور 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