Sử dụng TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk là ứng dụng khách TypeScript chính thức của chúng tôi dành cho Zinn Digital® API, được xuất bản trên npm. Mọi đường dẫn, tham số và phản hồi trong đó đều được tạo từ cùng một đặc tả OpenAPI mà API được xây dựng từ đó, đồng thời phiên bản mới sẽ được xuất bản tự động bất cứ khi nào đặc tả đó thay đổi. Hướng dẫn này sẽ cài đặt, xác thực và thực hiện các lệnh gọi đầu tiên của quý vị.

Cài đặt

npm install @zinn-digital/sdk

Thư viện này hoạt động trong mọi môi trường thực thi JavaScript có hỗ trợ fetch: Node.js, trình duyệt và các môi trường edge. Thư viện chỉ có một phần phụ thuộc lúc thực thi là openapi-fetch và được cấp phép theo MIT.

Tạo khóa API

Mở trang Khóa API trên bảng điều khiển của quý vị (app.zinndigital.com/api-keys) và nhấn Tạo khóa. Đặt tên cho khóa và chỉ cấp các quyền mà mã của quý vị cần — ví dụ: sites.view để liệt kê các trang web. Khóa chỉ được hiển thị một lần; hãy lưu trữ khóa trong biến môi trường hoặc kho lưu trữ bí mật của quý vị, tuyệt đối không để trong mã nguồn. Quý vị có thể thu hồi khóa bất kỳ lúc nào trên cùng trang này.

Các điểm cuối danh mục công khai, chẳng hạn như khu vực lưu trữ và các gói dịch vụ, hoàn toàn không cần khóa.

Các lệnh gọi đầu tiên của quý vị

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

Chạy lệnh này bằng ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Dòng đầu tiên in ra các khu vực lưu trữ, sau đó là mỗi trang web một dòng.

Các kiểu cho mã nguồn của riêng bạn

Các kiểu lược đồ đã được xuất, vì vậy các hàm của riêng bạn có thể sử dụng các cấu trúc của API:

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

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

Đường dẫn, tham số hoặc trường viết sai chính tả sẽ là lỗi biên dịch thay vì một yêu cầu âm thầm thực hiện sai thao tác.

Lỗi

Mỗi lệnh gọi đều trả về { data, error, response }. Đối với phản hồi không thuộc dải 2xx, data là không xác định và error là vỏ bọc lỗi của API: error.error.code, error.error.message mà con người có thể đọc được và đối với các trường hợp xác thực không thành công là error.error.details nêu rõ tên từng trường. Mã 403 có nghĩa là khóa không mang quyền mà điểm cuối yêu cầu — hãy tạo một khóa có quyền đó thay vì dùng lại khóa có nhiều quyền hơn.

Nơi chuyển tiếp tiếp theo

• Hướng dẫn trên trang web của chúng tôi: zinndigital.com/developers/sdk-typescript
• Mọi điểm cuối, các tham số và quyền của điểm cuối đó: zinndigital.com/developers/api
• Gói trên npm: npmjs.com/package/@zinn-digital/sdk