Paggamit ng TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk ang aming opisyal na TypeScript client para sa Zinn Digital® API, na nai-publish sa npm. Ang bawat path, parameter, at tugon dito ay binuo mula sa parehong detalye ng OpenAPI kung saan binuo ang API, at isang bagong bersyon ang awtomatikong nai-publish tuwing magbabago ang detalyeng iyon. Ini-install ito ng gabay na ito, pinapapatotohanan ito, at isinasagawa ang inyong mga unang tawag.

I-install

npm install @zinn-digital/sdk

Gumagana ito sa anumang JavaScript runtime na may fetch: Node.js, ang browser, at mga edge runtime. Mayroon itong isang runtime dependency, ang openapi-fetch, at ito ay lisensiyado sa ilalim ng MIT.

Gumawa ng API key

Buksan ang pahina ng Mga API key ng iyong dashboard (app.zinndigital.com/api-keys) at pindutin ang Gumawa ng key. Bigyan ang key ng pangalan at ang mga pahintulot lamang na kailangan ng iyong code — halimbawa sites.view upang ilista ang mga site. Isang beses lamang ipinapakita ang key; iimbak ito sa isang environment variable o sa iyong secret store, kailanman ay huwag sa source code. Maaari mong bawiin ang isang key anumang oras sa parehong pahina.

Ang mga pampublikong catalogue endpoint, tulad ng mga rehiyon at plano ng pag-host, ay hindi nangangailangan ng key kahit kailan.

Ang iyong mga unang tawag

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);

Patakbuhin ito gamit ang ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Ini-print ng unang linya ang mga rehiyon ng pag-host, pagkatapos ay isang linya bawat site.

Mga uri para sa sarili ninyong code

Naka-export ang mga uri ng schema, kaya magagamit ng sarili ninyong mga function ang mga hugis ng API:

import type { components } from "@zinn-digital/sdk";

type Site = components["schemas"]["Site"];
type DnsRecord = components["schemas"]["DnsRecord"];

Ang maling spelling ng path, parameter o field ay isang compile error sa halip na isang kahilingang tahimik na gumagawa ng maling bagay.

Mga Error

Bawat tawag ay nagbabalik ng { data, error, response }. Sa isang hindi-2xx na tugon, ang data ay undefined at ang error ay ang envelope ng error ng API: error.error.code, isang nababasang error.error.message para sa tao at, para sa mga pagkabigo sa pagpapatunay, error.error.details na nagpapangalan sa bawat field. Ang 403 ay nangangahulugang hindi taglay ng key ang pahintulot na kailangan ng endpoint — gumawa ng key na may ganoong pahintulot sa halip na muling gumamit ng isa na may higit pa.

Saan susunod na pupunta

• Ang gabay sa aming website: zinndigital.com/developers/sdk-typescript
• Bawat endpoint, ang mga parameter nito at ang pahintulot nito: zinndigital.com/developers/api
• Ang package sa npm: npmjs.com/package/@zinn-digital/sdk