Usando o SDK do TypeScript (@zinn-digital/sdk)

O @zinn-digital/sdk é o nosso cliente TypeScript oficial para a API da Zinn Digital®, publicado no npm. Cada caminho, parâmetro e resposta nele é gerado a partir da mesma especificação OpenAPI na qual a API é construída, e uma nova versão é publicada automaticamente sempre que essa especificação é alterada. Este guia o instala, realiza a autenticação e faz as suas primeiras chamadas.

Instalar

npm install @zinn-digital/sdk

Ele funciona em qualquer ambiente de execução JavaScript que disponha de fetch: Node.js, o navegador e ambientes edge. Ele possui uma dependência de tempo de execução, openapi-fetch, e é licenciado sob a licença MIT.

Crie uma chave de API

Abra a página Chaves de API do seu painel (app.zinndigital.com/api-keys) e pressione Criar uma chave. Dê um nome à chave e atribua apenas as permissões de que seu código necessita — por exemplo, sites.view para listar sites. A chave é exibida apenas uma vez; armazene-a em uma variável de ambiente ou em seu cofre de segredos, nunca no código-fonte. Você pode revogar uma chave a qualquer momento na mesma página.

Endpoints públicos do catálogo, como regiões de hospedagem e planos, não precisam de chave alguma.

Suas primeiras chamadas

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

Execute com ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. A primeira linha exibe as regiões de hospedagem, seguida por uma linha para cada site.

Tipos para o seu próprio código

Os tipos de esquema são exportados, para que suas próprias funções possam usar os formatos da API:

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

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

Um caminho, parâmetro ou campo com grafia incorreta é um erro de compilação, e não uma solicitação que faz silenciosamente a coisa errada.

Erros

Cada chamada retorna { data, error, response }. Em uma resposta diferente de 2xx, data fica indefinido e error é o envelope de erro da API: error.error.code, uma mensagem legível por humanos em error.error.message e, para falhas de validação, error.error.details identificando cada campo. Um erro 403 significa que a chave não possui a permissão necessária para o endpoint — crie uma chave com essa permissão em vez de reutilizar uma que contenha permissões em excesso.

Para onde ir em seguida

• O guia em nosso site: zinndigital.com/developers/sdk-typescript
• Cada endpoint, seus parâmetros e sua permissão: zinndigital.com/developers/api
• O pacote no npm: npmjs.com/package/@zinn-digital/sdk