Menggunakan TypeScript SDK (@zinn-digital/sdk)

@zinn-digital/sdk ialah klien TypeScript rasmi kami untuk API Zinn Digital®, yang diterbitkan di npm. Setiap laluan, parameter dan respons di dalamnya dijana daripada spesifikasi OpenAPI yang sama yang digunakan untuk membina API ini, dan versi baharu diterbitkan secara automatik setiap kali spesifikasi tersebut berubah. Panduan ini memasangnya, mengesahkannya dan membuat panggilan pertama anda.

Pasang

npm install @zinn-digital/sdk

Ia berfungsi dalam mana-mana masa jalanan JavaScript yang mempunyai fetch: Node.js, penyemak imbas dan masa jalanan edge. Ia mempunyai satu pergantungan masa jalanan, openapi-fetch, dan ia berlesen MIT.

Cipta kunci API

Buka halaman Kunci API papan pemuka anda (app.zinndigital.com/api-keys) dan tekan Cipta kunci. Berikan kunci itu nama dan hanya kebenaran yang diperlukan oleh kod anda — contohnya sites.view untuk menyenaraikan laman. Kunci tersebut ditunjukkan sekali sahaja; simpannya dalam pemboleh ubah persekitaran atau stor rahsia anda, jangan sekali-kali dalam kod sumber. Anda boleh membatalkan kunci pada bila-bila masa di halaman yang sama.

Titik akhir katalog awam, seperti rantau pengehosan dan pelan, tidak memerlukan kunci langsung.

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

Jalankannya dengan ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. Baris pertama mencetak rantau pengehosan, kemudian satu baris bagi setiap tapak.

Jenis untuk kod anda sendiri

Jenis skema dieksport, jadi fungsi anda sendiri boleh menggunakan bentuk API:

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

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

Laluan, parameter atau medan yang salah eja ialah ralat kompilasi dan bukannya permintaan yang secara senyap melakukan perkara yang salah.

Ralat

Setiap panggilan mengembalikan { data, error, response }. Pada respons bukan 2xx, data adalah tidak ditakrifkan dan error ialah sampul ralat API: error.error.code, error.error.message yang boleh dibaca manusia dan, untuk kegagalan pengesahan, error.error.details yang menamakan setiap medan. 403 bermaksud kunci tersebut tidak membawa kebenaran yang diperlukan oleh titik akhir — cipta kunci dengan kebenaran tersebut dan bukannya menggunakan semula kunci yang mempunyai lebih banyak kebenaran.

Ke mana seterusnya

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