SDK

Официальные SDK сгенерированы из того же apps/api/openapi.json, что и справочник API: одна функция на операцию, с теми же именами полей и кодами ошибок, что у REST. Ручного кода поверх генератора минимум — конструктор клиента и типы.

TypeScriptСкопировать ссылку

npm i typizer

import { createTypizerClient, getMe } from 'typizer';

const client = createTypizerClient({
  apiKey: process.env.TYPIZER_API_KEY as string,
  // baseUrl по умолчанию — https://api.typizer.ru
});

const { data, error } = await getMe({ client });
if (error) throw new Error(`typizer: ${JSON.stringify(error)}`);

console.log(data.organization.name);

createTypizerClient({ apiKey, baseUrl? }) собирает клиент @hey-api/client-fetch с заголовком Authorization: Bearer <apiKey>; baseUrl нужен только для нестандартного адреса (например, тестового окружения). Каждая сгенерированная функция (getMe, extract, createTypizer, listRuns, …) принимает этот клиент через { client, ... } и возвращает { data, error } — error заполнено при ответе с кодом ошибки, data — при успехе; исключение не бросается.

PythonСкопировать ссылку

pip install typizer

import os

from typizer import AuthenticatedClient
from typizer.api.account import get_me
from typizer.models import Me

client = AuthenticatedClient(
    base_url="https://api.typizer.ru",
    token=os.environ["TYPIZER_API_KEY"],
)

me = get_me.sync(client=client)
if not isinstance(me, Me):
    raise RuntimeError(f"typizer: {me}")

print(me.organization.name)

AuthenticatedClient(base_url, token) — token это сам ключ (tz_live_…), без слова Bearer: клиент сам добавляет заголовок Authorization: Bearer <token>. Каждая операция — отдельный модуль (typizer.api.<тег>.<операция>, тег — из REST API, например typizer.api.runs.extract) с четырьмя функциями: sync/sync_detailed — блокирующие, asyncio/asyncio_detailed — асинхронные; sync/asyncio возвращают разобранную модель (или объект ошибки Problem, или None при неожиданном коде), *_detailed — весь Response целиком, со статусом и заголовками.

Что дальшеСкопировать ссылку

• «Справочник API» — REST-операция за каждой функцией SDK, например GET /v1/me за getMe выше.
• «Первый вызов API» — тот же первый запрос без SDK, сырым fetch/curl.
• «Обработка ошибок и повторов» — Idempotency-Key и коды ошибок, одинаковые что с SDK, что без него.