TypeScript SDK (@zinn-digital/sdk) қолдану

@zinn-digital/sdk — npm-де жарияланған Zinn Digital® API үшін ресми TypeScript клиентіміз. Ондағы әрбір жол, параметр және жауап API құрылған сол OpenAPI сипаттамасынан жасалады және сол сипаттама өзгерген сайын жаңа нұсқа автоматты түрде жарияланады. Бұл нұсқаулық оны орнатуды, аутентификациялауды және алғашқы шақыруларыңызды жасауды сипаттайды.

Орнату

npm install @zinn-digital/sdk

Бұл fetch қолдайтын кез келген JavaScript ортасында жұмыс істейді: 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