Истифодаи 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