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