Библиотеки

API — обычный HTTP, но библиотека предлагает использовать меньше кода и допускать меньше ошибок. Например, она повторяет запрос при перегрузке, проверяет параметры до отправки и превращает ответы в понятные исключения.

Одинаковые во всех языках#

Библиотеки сделаны по одной политике и проверены одними и теми же тестами, поведение у всех одинаковое:

• Методы — html, url, markdown, office, me и низкоуровневый convert для всего остального.
• Ключ — из переменной окружения PDFAPI_KEY, адрес — из PDFAPI_BASE_URL. Нет ключа — ошибка сразу при создании клиента, а не 401 при первом запросе.
• Проверка до запроса — размеры с единицами измерения, waitDelay до 10 секунд, адрес с http(s)://, файл Office — настоящий ZIP до 3,7 МБ. Ошибка аргумента не тратит ни запрос, ни лимит частоты.
• Повторы — 429 через Retry-After, 503 и неустановленное соединение — с нарастающей паузой, до двух раз. Таймауты не повторяются: в редком случае страницы могли уже списаться.
• Сохранение — save пишет атомарно: если запись оборвётся, прежний файл останется целым.
• Ключ не утекает — его нет в строковом представлении клиента, в текстах ошибок и журналах.

Ошибки#

Если что-то пошло не так, библиотека выдаёт ошибку с понятным названием: кончились страницы — QuotaExceededError, слишком частые запросы — RateLimitError. Так в коде можно по-разному реагировать на разные проблемы. А если причина неважна, ловите PdfApiError из первой строки таблицы — он перехватывает любую ошибку pdfapi.

Примеры#

У каждой библиотеки одни и те же примеры: счёт из HTML-шаблона, страница по адресу, документ Office, пачка документов с ограничением частоты, проверка квоты для cron и отдача PDF из веб-приложения.

Нет библиотеки для вашего языка — API работает с любым HTTP-клиентом: см. справочник. В скором времени добавим ещё несколько языков программирования.