TypeScript SDK(@zinn-digital/sdk) 사용하기

@zinn-digital/sdk는 npm에 게시된 Zinn Digital® API용 공식 TypeScript 클라이언트입니다. 내부의 모든 경로, 매개변수 및 응답은 해당 API가 빌드된 동일한 OpenAPI 사양에서 생성되며, 해당 사양이 변경될 때마다 새 버전이 자동으로 게시됩니다. 이 가이드에서는 설치, 인증 및 첫 번째 호출 수행 과정을 안내합니다.

설치

npm install @zinn-digital/sdk

fetch를 지원하는 모든 JavaScript 런타임에서 작동합니다: Node.js, 브라우저 및 엣지 런타임. 런타임 종속성은 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는 undefined이며 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