Menggunakan TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk adalah klien TypeScript resmi kami untuk Zinn Digital® API, yang dipublikasikan di npm. Setiap jalur, parameter, dan respons di dalamnya dihasilkan dari spesifikasi OpenAPI yang sama dengan yang digunakan untuk membangun API tersebut, dan versi baru akan dipublikasikan secara otomatis setiap kali spesifikasi tersebut berubah. Panduan ini memasangnya, mengautentikasinya, dan melakukan panggilan pertama Anda.

Pasang

npm install @zinn-digital/sdk

Ini berfungsi di runtime JavaScript apa pun yang memiliki fetch: Node.js, browser, dan runtime edge. Ini memiliki satu dependensi runtime, openapi-fetch, dan berlisensi MIT.

Buat kunci API

Buka halaman Kunci API di dasbor Anda (app.zinndigital.com/api-keys) dan tekan Buat kunci. Beri nama kunci dan berikan hanya izin yang dibutuhkan oleh kode Anda — misalnya sites.view untuk mencantumkan situs. Kunci hanya ditampilkan sekali; simpan di variabel lingkungan atau penyimpanan rahasia Anda, jangan pernah di kode sumber. Anda dapat mencabut kunci kapan saja di halaman yang sama.

Titik akhir katalog publik, seperti wilayah dan paket hosting, tidak memerlukan kunci sama sekali.

Panggilan pertama Anda

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

Jalankan dengan ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Baris pertama mencetak wilayah hosting, kemudian satu baris per situs.

Tipe untuk kode Anda sendiri

Tipe skema diekspor, sehingga fungsi Anda sendiri dapat menggunakan bentuk-bentuk API:

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

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

Jalur, parameter, atau bidang yang salah eja merupakan kesalahan kompilasi, bukan permintaan yang secara diam-diam melakukan tindakan yang salah.

Kesalahan

Setiap panggilan mengembalikan { data, error, response }. Pada respons selain 2xx, data tidak terdefinisi dan error adalah amplop kesalahan API: error.error.code, error.error.message yang dapat dibaca manusia, dan untuk kegagalan validasi, error.error.details yang menyebutkan setiap bidang. 403 berarti kunci tidak membawa izin yang dibutuhkan titik akhir — buat kunci dengan izin tersebut alih-alih menggunakan kembali kunci yang memiliki izin lebih banyak.

Ke mana selanjutnya

• Panduan di situs web kami: zinndigital.com/developers/sdk-typescript
• Setiap titik akhir, parameternya, dan izinnya: zinndigital.com/developers/api
• Paket di npm: npmjs.com/package/@zinn-digital/sdk