Протокол обмена между клиентом и сервером
Все запросы от клиентов к серверу ЛитРес осуществляются на сервер catalit.litres.ru по протоколу HTTPS. На клиента возлагается обязанность проверки корректности https-ключей сервера.
Все запросы отправляются на URL /catalitv2 методом POST.
Если не оговорено иное, все ответы сервера отдаются в виде JSON, сжатого по алгоритму gzip (о чем сообщает стандартный заголовок HTTP-ответа Content-Encoding: gzip), в кодировке UTF-8 (о чем сообщает HTTP-заголовок Content-type: application/json; charset=utf-8).
Иные заголовки свидетельствуют о фатальной внутренней ошибке сервера и должны обрабатываться на клиенте соответствующим образом.В некоторых случаях клиент может и/или должен подключиться к серверу по стандартному HTTP/HTTPS (в обход API) и забрать бинарные данные. Например, напрямую запрашивается файл обложки в формате JPEG. Такие случаи оговариваются отдельно.
Общее замечание: REST
Работа с API ЛитРес для любой программы-клиента строится по state-less схеме запрос-ответ: клиент формирует и передает запрос с параметрами, а сервер в ответ возвращает JSON-документ с ответом.
Один запрос приложения-клиента может (и будет, в большинстве случаев) содержать несколько обращений к API. Т. е. в рамках одного HTTP-запроса на сервер будет передан «пакет» запросов к API и сервер вернет единый JSON.
Формат подачи запросов к API и ответов
Все параметры запроса клиент передает в одном JSON, помещенном в HTTP-параметр jdata.
JSON в POST-параметре jdata должен быть передан в валидном UTF-8 и быть соответствующим образом закодирован для отправки в качестве POST-параметра.
Ответ сервера всегда (если не оговорено иное) отдается в виде валидного JSON, кодировка UTF-8.
JSON, отдаваемый сервером ЛитРес может (и будет) содержать избыточные данные в сравнении с тем, что описано в документации. Приложение должно без ошибок обрабатывать избыточность такого рода. Если избыточные данные не описаны в документации, клиенту следует их игнорировать.
Общие замечания о содержании JSON
JSON-запрос к серверу содержит объект с несколькими полями. Ключевой параметр requests содержит массив вызовов API.
Каждый запрос к API должен иметь уникальный ID. По этому ID результаты работы конкретного вызова можно будет найти в ответе.
В каждом запросе обязательно должен передаваться валидный SID. Исключением являются три запроса, позволяющие получить SID: обычная авторизация (w_create_sid), авторизация через соцсеть (w_authorise_socnet) и регистрация (w_register_user).
В любом запросе к API может передаваться параметр uilang. Параметр определяет локализацию интерфейсных элементов. Если запрашиваемые элементы не локализованы, будут возвращены результаты на русском языке. Параметр uilang является опциональным, при его отсутствии выдаются результаты на русском языке. Язык в параметре должен быть указан в стандарте ISO 639-2, например: rus, est, lav. Если указанный в параметре язык не поддерживается или указан не по стандарту, будет возвращена ошибка запроса ‘unknown language’
Время в запросе соотносится с временем сервера. В любом ответе сервера, в т. ч. в ответе о невалидном времени запроса, есть валидное серверное время (см. Пример структуры полноценного JSON ответа). Клиенту следует подстроиться под серверное время, учитывая разницу между временем сервера и локальным временем. Сервер ожидает, что любой запрос будет содержать корректное время и забота об этом возлагается на приложение-клиент.
Общий размер переданного JSON не может превышать 1 мегабайт.
Если в запросе к серверу или в ответе есть время (в данных или в параметрах запроса) оно должно передаваться в ISO-формате с таймзоной, например:
2014-11-07T16:21:02+03:00
Подпись и ограничение по частоте запросов
Запросы, доступные авторизованным приложениям, должны передавать ID приложения (app), время (time) и sha-подпись (sha).
SHA-подпись – хеш SHA-256, состоящий из прямой конкатенации строк time и secret_key):$sha=Digest::SHA::sha256_hex($time.$secret_key)
Один time можно использовать только ОДИН раз (!).
Не рекомендуется совершать более 1-го запроса в секунду. Если приложению надо быстро получить с сервера разнородные данные приложению следует сформировать одно обращение к API, содержащие множественные запросы.
Если (по тем или иным причинам) приложению необходимо делать частые запросы, следует передавать разное клиентское время. Поскольку сервер позволяет отклонения клиентского времени в диапазоне 10 минут кратковременный «флуд» технически возможен.
Серверное ПО может (по своему усмотрению) заблокировать подозрительную активность приложений при запросах чаще, чем раз в секунду. Проектируйте приложение так, чтобы только нечеловеческая реакция и гиперактивность пользователя могли привести к частым запросам, не делайте десять запросов там, где можно сделать один.
Captcha
Любой запрос к серверу может вернуть вместо штатного ответа требование пройти captcha-тест (см. Пример JSON ответа «captcha-тест»).
Captcha-тест проводится отображением клиенту HTML-окна браузера (например в WebView).
URL, который надо показать пользователю, передается в ответе.
После успешной проверки пользователь будет перенаправлен на URL /captaha_ok. После этого клиент может повторить свой первоначальный запрос.
Получение ознакомительных фрагментов
Для большинства книг доступен ознакомительный фрагмент, который можно получить с сервера ЛитРес. Ссылка на получение ознакомительного фрагмента формируется в зависимости от типа книги.
- Ознакомительные фрагменты для текстовых книг. Для текстовых форматов (fb2.zip, fb3, ePub, rtf.zip, txt, txt.zip, a4.pdf, a6.pdf) ознакомительный фрагмент с сервера ЛитРес можно получить по ссылке вида: https://catalit.litres.ru/pub/t/123456.fb2.zip, где 123456 – ID книги, a вместо fb2.zip можно подставить другое расширение.
- Ознакомительные фрагменты для PDF-книг. Для всех PDF-книг доступны ознакомительные фрагменты. URL для ознакомительного фрагмента формируется как https://catalit.litres.ru/get_pdf_trial/123456.pdf, где 123456 – ID книги. Фрагмент является PDF-файлом, обычно содержащим несколько первых страниц (например, может быть 25 страниц).
- Ознакомительные фрагменты для аудио-книг. Для всех аудио-книг доступны ознакомительные фрагменты. URL для ознакомительного фрагмента формируется как https://catalit.litres.ru/get_mp3_trial/123456.mp3, где 123456 – ID книги, ознакомительный фрагмент представлен mp3-файлом.
Оформление документа
Обязательные параметры помечены красной звездочкой:
login* – вот так.
Имейте в виду, что иногда ни один параметр не является обязательным, но существует группа параметров, в которой хотя бы один должен быть указан. Например, при регистрации можно указать и логин, и e-mail, либо что-то одно, но совсем не передать ни логина, ни e-mail – нельзя. Такие случаи оговариваются отдельно.