ການນຳໃຊ້ TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk ແມ່ນ TypeScript client ທາງການຂອງພວກເຮົາສຳລັບ Zinn Digital® API, ເຊິ່ງຖືກເຜີຍແຜ່ຢູ່ເທິງ npm. ທຸກໆ path, parameter ແລະ response ຢູ່ໃນນັ້ນແມ່ນຖືກສ້າງຂຶ້ນມາຈາກ OpenAPI specification ດຽວກັນກັບທີ່ API ຖືກສ້າງຂຶ້ນ, ແລະ ເວີຊັນໃໝ່ຈະຖືກເຜີຍແຜ່ໂດຍອັດຕະໂນມັດທຸກຄັ້ງທີ່ specification ນັ້ນມີການປ່ຽນແປງ. ຄູ່ມືນີ້ຈະຕິດຕັ້ງ, ຢືນຢັນຕົວຕົນ ແລະ ເຮັດການຮຽກໃຊ້ງານຄັ້ງທຳອິດຂອງທ່ານ.

ຕິດຕັ້ງ

npm install @zinn-digital/sdk

ມັນເຮັດວຽກໄດ້ໃນທຸກໆ JavaScript runtime ທີ່ມີ fetch: Node.js, ບຣາວເຊີ ແລະ edge runtimes. ມັນມີການເພິ່ງພາ runtime ພຽງອັນດຽວ ຄື openapi-fetch, ແລະ ໄດ້ຮັບອະນຸຍາດພາຍໃຕ້ MIT.

ສ້າງຄີ API

ເປີດໜ້າ ຄີ API ໃນແຜງຄວບຄຸມຂອງທ່ານ (app.zinndigital.com/api-keys) ແລ້ວກົດ ສ້າງຄີ. ຕັ້ງຊື່ໃຫ້ຄີ ແລະ ໃຫ້ສະເພາະສິດອະນຸຍາດທີ່ໂຄ້ດຂອງທ່ານຕ້ອງການ — ຕົວຢ່າງ sites.view ເພື່ອສະແດງລາຍຊື່ເວັບໄຊ. ຄີຈະຖືກສະແດງພຽງຄັ້ງດຽວເທົ່ານັ້ນ; ໃຫ້ເກັບຮັກສາມັນໄວ້ໃນຕົວປ່ຽນສະພາບແວດລ້ອມ ຫຼື ບ່ອນເກັບຂໍ້ມູນລັບຂອງທ່ານ, ຢ່າເກັບໄວ້ໃນ source code ເດັດຂາດ. ທ່ານສາມາດຖອນການນຳໃຊ້ຄີໄດ້ທຸກເວລາໃນໜ້າດຽວກັນນີ້.

ປາຍທາງເຊື່ອມຕໍ່ລາຍການສາທາລະນະ ເຊັ່ນ: ພາກພື້ນໂຮສຕິ້ງ ແລະ ແຜນການຕ່າງໆ ແມ່ນບໍ່ຈຳເປັນຕ້ອງມີຄີເລີຍ.

ການເອີ້ນໃຊ້ຄັ້ງທຳອິດຂອງທ່ານ

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