שימוש ב-TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk הוא לקוח ה-TypeScript הרשמי שלנו עבור ה-API של Zinn Digital®, המפורסם ב-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"];

נתיב, פרמטר או שדה עם שגיאת כתיב מהווים שגיאת הידור (compile error) ולא בקשה שמבצעת בשקט את הפעולה השגויה.

שגיאות

כל קריאה מחזירה { 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