การใช้งาน 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 จะไม่ถูกกำหนด และ 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