ナレッジベース

TypeScript SDK (@zinn-digital/sdk) の使用

npm から @zinn-digital/sdk をインストールし、API キーを作成して、TypeScript から Zinn Digital® API への最初の型定義された呼び出しを行います — キー不要のパブリックリージョン、次に独自のサイト — さらにエクスポートされたスキーマ型とエラーの返却方法についても説明します。

@zinn-digital/sdkは、npm で公開されている Zinn Digital® API 向けの公式 TypeScript クライアントです。含まれるすべてのパス、パラメーター、レスポンスは、API の構築元と同じ OpenAPI 仕様から生成されており、その仕様が変更されるたびに新しいバージョンが自動的に公開されます。このガイドでは、インストール、認証を行い、最初のリクエストを実行します。

インストール

npm install @zinn-digital/sdk

Node.js、ブラウザ、エッジランタイムなど、fetch を備えたあらゆる JavaScript ランタイムで動作します。ランタイムの依存関係は openapi-fetch の1つのみで、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 で実行してください。最初の行にホスティングリージョンが出力され、その後にサイトごとに1行ずつ出力されます。

独自のコード用の型

スキーマの型がエクスポートされているため、独自に関数で 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 は、エンドポイントが必要とする権限がキーに含まれていないことを意味します。より強い権限を持つキーを再利用するのではなく、その権限を持つキーを作成してください。