Клиентские библиотеки

REST API — это обычный HTTP и обычный JSON, и вызова fetch вполне достаточно, чтобы им пользоваться. Клиентские библиотеки существуют ради того, что никому не хочется писать дважды: правильный повтор запроса, упёршегося в лимит частоты, безопасное повторное создание и обход курсора до конца списка.

Три библиотеки, один контракт:

| Язык | Пакет | Исходники | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

Установка

Пакетов пока нет ни в npm, ни в PyPI, ни в Packagist. Публикация ждёт аккаунтов в реестрах; код готов и уже сегодня ставится из копии репозитория, а команды ниже превратятся в однострочный npm install @linkprofit/sdk (и его аналоги), как только аккаунты появятся.

Node, из локальной копии репозитория:

npm install /path/to/linkprofit/packages/sdk-node

Python, из локальной копии репозитория:

pip install /path/to/linkprofit/sdk/python

PHP, через path-репозиторий Composer в вашем composer.json:

{
  "repositories": [
    { "type": "path", "path": "/path/to/linkprofit/sdk/php" }
  ],
  "require": {
    "linkprofit/linkprofit-php": "*"
  }
}

Что все три делают одинаково

Библиотеки нарочно скучные и нарочно похожие. Разберитесь в поведении один раз — и оно окажется тем же самым на любом языке.

Аутентификация. Вы передаёте ключ рабочего пространства (lp_live_…), а клиент проставляет заголовок Authorization в каждом запросе. Базовый адрес — это параметр, поэтому один и тот же код в тестах работает с локальным экземпляром. Об областях действия и ротации читайте в аутентификации.

Повторы, уважающие сервер. 429 и временный 5xx повторяются с отступом, а Retry-After соблюдается, а не угадывается: сервер уже знает, когда окно освободится. Число попыток ограничено, а запрос, отклонённый по существу (validation_failed, conflict, not_found), не повторяется никогда: повторять неверный запрос — значит впустую тратить бюджет лимита частоты.

Идемпотентные изменения. Каждый изменяющий вызов несёт Idempotency-Key, поэтому повтор после сетевого таймаута вернёт сохранённый ответ вместо создания второй ссылки. Свой ключ — идентификатор заказа, идентификатор задачи — можно передать самому, когда повтор придёт из другого процесса или из более позднего запуска. Ключи хранятся 24 часа; тот же ключ с другим телом запроса отвечает 409.

Курсорная пагинация как итератор. Списочные эндпоинты разбиты курсорами, и клиенты отдают их итераторами: вы просто идёте по ссылкам, клиент подтягивает следующую страницу, когда текущая кончилась, и останавливается, когда курсор равен null. Никакой арифметики страниц и никакого риска ошибки на единицу, из-за которой запись молча теряется.

Ошибки как исключения. Неудача поднимает исключение, естественное для языка, и несёт code из API, человеческое сообщение и — для ошибок валидации — details по каждому полю. Ветвитесь по коду, а не по тексту сообщения: контракт задают именно коды.

Типы запросов и ответов клиента для Node генерируются из того же документа OpenAPI, который отрисовывает справочник и который опубликован по адресу /openapi.json, — поэтому типы не могут разойтись с работающим API. Клиенты для Python и PHP следуют тому же документу вручную, в идиоматике своего языка.

Быстрый старт

В каждом пакете лежит README с полным набором возможностей; сниппеты ниже показывают форму, общую для всех трёх: создать клиент с ключом, вызвать группу ресурсов, получить в ответ типизированный объект.

Node

import { LinkProfit } from "@linkprofit/sdk";

const client = new LinkProfit({ apiKey: process.env.LINKPROFIT_API_KEY });

const created = await client.createLink({
  url: "https://example.com/summer-sale",
  title: "Summer sale",
});

console.log(created.data.short_url);

Python

import os

from linkprofit import LinkProfit

client = LinkProfit(os.environ["LINKPROFIT_API_KEY"])

created = client.create_link(
    {"url": "https://example.com/summer-sale", "title": "Summer sale"}
)

print(created["data"]["short_url"])

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LinkProfit\LinkProfit;

$client = new LinkProfit(getenv('LINKPROFIT_API_KEY'));

$created = $client->createLink([
    'url' => 'https://example.com/summer-sale',
    'title' => 'Summer sale',
]);

echo $created['data']['short_url'];

Какую выбрать

• Node / TypeScript — самый полный набор возможностей, потому что типы берутся прямо из документа OpenAPI. Естественный выбор для бэкенда на JavaScript, для serverless-функции или сборочного скрипта.
• Python — для отчётности и работы с данными: вытащить аналитику в блокнот, в задание по расписанию или в поток данных для дашборда.
• PHP — для мира CMS. Плагин WordPress или сервис на Laravel, который сокращает ссылки прямо в момент публикации материала.
• Никакую — если ваш язык не из этого списка, API остаётся обычным HTTP. Быстрый старт написан прежде всего на curl, а всё, что делают клиенты (повторы, идемпотентность, курсоры), — это описанное поведение, которое реализуется в полсотни строк.

Что бы вы ни выбрали, справочник API остаётся полным перечнем эндпоинтов, полей и кодов ошибок: библиотеки — удобная обёртка над ним, а не другое API.

Что ещё стоит прочитать

• Лимиты частоты — бюджет, внутри которого работает логика повторов.
• Webhook — получайте события сами, вместо того чтобы опрашивать API.
• MCP-сервер — те же операции из ИИ-ассистента.