Uso del SDK de TypeScript (@zinn-digital/sdk)

@zinn-digital/sdk es nuestro cliente oficial de TypeScript para la API de Zinn Digital®, publicado en npm. Cada ruta, parámetro y respuesta en él se genera a partir de la misma especificación OpenAPI en la que se basa la API, y se publica una nueva versión automáticamente cada vez que cambia dicha especificación. Esta guía lo instala, lo autentica y realiza sus primeras llamadas.

Instalar

npm install @zinn-digital/sdk

Funciona en cualquier entorno de ejecución de JavaScript que tenga fetch: Node.js, el navegador y los entornos de ejecución edge. Tiene una dependencia de tiempo de ejecución, openapi-fetch, y cuenta con licencia MIT.

Crear una clave de API

Abra la página Claves de API de su panel de control (app.zinndigital.com/api-keys) y presione Crear una clave. Asigne un nombre a la clave y solo los permisos que su código necesite; por ejemplo, sites.view para listar sitios. La clave se muestra una sola vez; guárdela en una variable de entorno o en su almacén de secretos, nunca en el código fuente. Puede revocar una clave en cualquier momento en la misma página.

Los extremos públicos del catálogo, como las regiones de alojamiento y los planes, no necesitan ninguna clave.

Sus primeras llamadas

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

Ejecútelo con ZINN_API_KEY=zdk_live_… npx tsx first-calls.ts. La primera línea imprime las regiones de alojamiento, luego una línea por sitio.

Tipos para su propio código

Los tipos de esquema se exportan, por lo que sus propias funciones pueden usar las estructuras de la API:

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

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

Una ruta, un parámetro o un campo mal escritos constituyen un error de compilación y no una solicitud que hace algo incorrecto de forma silenciosa.

Errores

Cada llamada devuelve { data, error, response }. En una respuesta distinta de 2xx, data es indefinido y error es la envoltura de error de la API: error.error.code, un mensaje legible por humanos error.error.message y, en caso de fallos de validación, error.error.details especificando cada campo. Un 403 significa que la clave no contiene el permiso que el punto de conexión necesita; cree una clave con ese permiso en lugar de reutilizar una con permisos adicionales.

Adónde ir a continuación

• La guía en nuestro sitio web: zinndigital.com/developers/sdk-typescript
• Cada punto de conexión, sus parámetros y su permiso: zinndigital.com/developers/api
• El paquete en npm: npmjs.com/package/@zinn-digital/sdk