Документация API

Три метода, без регистрации и без ключа. Ограничение — 60 запросов в минуту с одного IP (кратковременный всплеск до 10 запросов допустим).

1. Поиск по ISBN

GET /api/v1/search/isbn/{isbn}

Если книги нет в базе — сервис автоматически подтянет данные из Open Library, Google Books, FantLab и других источников и сохранит на будущее. Первый запрос по новому ISBN может занять несколько секунд, повторный — мгновенный.

curl "https://ваш-домен/api/v1/search/isbn/9785389143852"

[
  {
    "guid": "c1eac6ea-ecac-4206-9121-d030cfbc9ff2",
    "Title": "Дорога",
    "AuthorName": "Кормак Маккарти",
    "Publisher": "Азбука",
    "PublishedYear": 2018,
    "ISBN": "9785389143852",
    "CoverUrl": "https://covers.openlibrary.org/b/id/12196387-L.jpg"
  }
]

Если книгу не удалось найти нигде — вернётся пустой массив [], а не ошибка.

2. Поиск по названию

GET /api/v1/search/title?q=...

Возвращает массив — по названию может найтись несколько изданий одной книги или несколько разных книг со сходным названием. Выбор нужного издания — на стороне вашего приложения.

curl "https://ваш-домен/api/v1/search/title?q=Мастер+и+Маргарита"

3. Универсальный поиск

GET /api/v1/search?q=...

Сам определяет по контрольной сумме, похож ли запрос на ISBN, и вызывает нужный метод. Удобен, если в вашем приложении одно поле ввода на всё.

curl "https://ваш-домен/api/v1/search?q=9785171234567"
curl "https://ваш-домен/api/v1/search?q=Мастер+и+Маргарита"

Выбор полей — ?fields=

По умолчанию возвращается полный набор публичных полей. Можно запросить только нужные — например, для автокомплита в UI достаточно названия и автора:

curl "https://ваш-домен/api/v1/search/title?q=дорога&fields=Title,AuthorName"

Доступные поля: Title, Subtitle, AuthorName, Publisher, PublishedYear, ISBN, ISBN13, CoverUrl, Genre, Description, Pages, Language, Series, SeriesNumber, Rating, Format, AgeRestriction. Неизвестные имена в fields просто игнорируются — опечатка не приведёт к ошибке, вернётся набор по умолчанию.

Публичные счётчики

GET /api/v1/public/stats

curl "https://ваш-домен/api/v1/public/stats"

{
  "totalBooks": 1284,
  "booksAddedToday": 12,
  "authorsVerified": 640,
  "requestsToday": 355,
  "updatedAt": "2026-08-30T14:00:00Z"
}

Обновляются раз в час — это снапшот, не live-счёт.

Коды ошибок

Код	Когда
400	Невалидный ISBN (не прошёл проверку контрольной суммы) или не передан ни `isbn`, ни `q`
429	Превышен лимит запросов (60/мин, burst 10) — подождите и повторите
500	Внутренняя ошибка — если повторяется стабильно, напишите нам

Полная машиночитаемая спецификация (OpenAPI) — в Swagger UI или напрямую в /api-docs для автогенерации клиентов.