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

Основная информация

Полный путь для подключения: https://profspo.ru/api/.
Данные передаются методом GET. Допустимы два формата:
1. Прямая передача параметров в строке запроса:
  https://profspo.ru/api/any?key=value&param=true
2. Передача параметров в JSON-объекте, если приложение основано на библиотеках JavaScript: на https://profspo.ru/api/any передаются данные { "key": "value", "param": true }.
Любой запрос на сервер должен сопровождаться двумя обязательными параметрами: organization_id и access_token. Эти данные можно получить в соответствующем разделе (доступен только зарегистрированным пользователям с соответствующими полномочиями). Данные можно передавать в следующем формате: { "organization_id": "24", "access_token": "XXXX.ZZZZ.QJGWT" } или в виде строки запроса в URL. Токен доступа соответствует формату JWT. В случае отсутствия этой пары значений либо в случае их невалидности вместо необходимых данных будет получено сообщение об ошибке, связанной с некорректным токеном.
Есть разделы, требующие авторизации (это каждый раз отмечено в документации особо), а есть те, которые не требуют. При авторизации проверяются также привилегии авторизованного пользователя.
Ответ сервера на любой запрос включает 4 секции: { "success": true или false , "status": 200 или 404, "message": пустое сообщение или сообщение об ошибке, "data": массив с полученными данными }.

Авторизация

Для авторизации следует передать на URL https://profspo.ru/api/login данные в формате: { "email": "e-mail пользователя", "password": "пароль" }.
Как и прочие параметры, передаваемые на сервер, данные авторизации следует передавать в виде единого JSON-объекта вместе с токеном доступа и id организации, например, так: { "organization_id": "24", "access_token": "XXXX.ZZZZ.QJGWT", "email": "user@user.ru", "password": "123456" }. Далее в документации это отдельно не оговаривается и не приводится в примерах, но передача токена и id организации является обязательной всегда.
При неудачном выполнении авторизации в ответ будут получены данные с детальным сообщением об ошибке.
При успешном выполнении авторизации в ответ будут получены данные о пользователе и его организации, а также ID пользователя и токен, сгенерированный для данного пользователя (у пользователя может быть несколько токенов в разных приложениях). Пример: { "success": true, "status": 200, "message": "Успешная авторизация.", "data": { "user_id": 123, "user_token": "XXXXX" } }. Эти данные внутри приложения можно сохранить в Cookie или в любом другом локальном хранилище для последующего использования.
Полученные данные user_id и user_token следует использовать для доступа ко всем разделам, требующим авторизации. Например, для доступа к списку организаций на URL https://profspo.ru/api/organizations следует передать данные в формате { "user_id": 123, "user_token": "XXXXX" }.
Если какие-либо разделы предполагают не только авторизацию, но и передачу дополнительных данных, эти данные следует передавать единым объектом вместе с данными авторизации, например, { "id": 1, "user_id": 123, "user_token": "XXXXX" }.
Для разавторизации пользователя следует передать на URL https://profspo.ru/api/logout данные в формате: { "id": 1, "user_id": 123, "user_token": "XXXXX" }. В этом случае токен будет уничтожен, и последующая передача этих данных на разделы, требующие авторизации, будет приводить к ответу с сообщением об ошибке авторизации.

Доступные разделы каталога

https://profspo.ru/api/books — список книг.
Вывод изданий ограничивается числом, которое можно изменить.
Возвращаемые данные внутри секции data:
- values — данные об изданиях (ключ cover включает путь к обложке)
- total — общее количество изданий (требуется для постраничного вывода и статистики)
Допустимые параметры:
- limit — число выводимых изданий (максимум 100)
- offset — смещение для постраничного вывода
- id — получение данных о конкретном издании по его id
- s — поиск по названию издания
- escape — вывод данных в формате Escaped Unicode (универсальный параметр, можно применять для любого запроса)
Возвращается только информация об изданиях из коллекций, которые доступны по подписке для данной организации; в случае в организациями типа Premium, возвращается информация обо всех изданиях, включённые во все коллекции, за исключением издательских: информация об изданиях, включённых в издательские коллекции, если для данной организации осуществлена подписка на данную издательскую коллекцию.
https://profspo.ru/api/periodicals — список периодических изданий.
Возвращаемые данные и допустимые параметры аналогичны разделу books.
Кроме того, для каждого периодического издания ключ issues отвечает за выпуски, рассортированные по годам.

Пользователи

https://profspo.ru/api/userlist — список пользователей.
Вывод пользователей ограничивается числом, которое можно изменить.
Возвращаемые данные внутри секции data:
- values — данные о пользователях
- total — общее количество пользователей (требуется для постраничного вывода и статистики)
- user — данные об авторизованном пользователе
Допустимые параметры:
- limit — число выводимых пользователей (максимум 100)
- offset — смещение для постраничного вывода
- id — получение данных о конкретном пользователе по его id
- s — поиск по имени пользователя
- escape — вывод данных в формате Escaped Unicode (универсальный параметр, можно применять для любого запроса)
Важно: для данного запроса требуется авторизация.
https://profspo.ru/api/create-user — создание пользователя.
Принимаемые параметры:
- name — имя пользователя (строка от 3 до 50 символов)
- email — e-mail (строка)
- password — пароль (от 6 символов)
- role — роль пользователя (допустимые значения: 2 — обучающийся, 5 — преподаватель)
- is_blocked (необязательный) — блокировка пользователя (допустимые значения: 0 — отсутствие блокировки, 1 — пользователь заблокирован)
- select_organization (необязательный) — числовой идентификатор связанной организации, для которой ваша организация, выпустившая токен доступа, является координатором; пользователь будет зарегистрирован внутри указанной связанной организации
Возвращаемые данные внутри секции data в случае успешного создания пользователя:
- user_id — числовой идентификатор созданного пользователя
Важно: для данного запроса требуется авторизация.
https://profspo.ru/api/update-user — обновление данных пользователя. Обновлять данные пользователя могут библиотекари, менеджеры, администраторы и он сам.
Принимаемые параметры:
- edited_user_id — числовой идентификатор пользователя, данные которого требуется обновить
- а также любой из принимаемых параметров раздела create-user по отдельности или в любом сочетании (т.е. обновить можно как все данные, так и каждое поле по отдельности, и только некоторые, а в случае с параметром is_blocked можно заблокировать или разблокировать пользователя)
Данные внутри секции data не возвращаются.
Важно: для данного запроса требуется авторизация.
https://profspo.ru/api/related-organizations — список связанных организаций, для которых ваша организация, выпустившая токен доступа, является координатором.
Возвращаемые данные внутри секции data:
- values — данные о связанных организациях (идентификатор и название для каждой)

Бесшовная авторизация

https://profspo.ru/api/login-once-token/ID — запрос ссылки для однократной авторизации пользователя с указанием идентификатора, где ID — числовой идентификатор пользователя.
Допустимые параметры:
- url — URL страницы (без имени сервера, протокола, ведущих и завершающих слэшей), на которую нужно переадресовать пользователя после успешной авторизации, например, catalog, books/87914, recent, profile/17.
Возвращаемые данные внутри секции data:
- link — ссылка вида https://profspo.ru/api/login-once/256/XXXXXX, которую необходимо сообщить пользователю с id, переданным в запросе; при переходе по ссылке пользователь авторизуется в системе, а токен для ссылки уничтожается, так что ссылку повторно использовать не получится
https://profspo.ru/api/login-or-register-token — запрос ссылки для однократной авторизации или регистрации пользователя. При запросе ссылки пользователь, если он отсутствует в системе, не создаётся до того момента, как ссылка не будет использована.
Необходимые параметры:
- email — e-mail пользователя, который должен быть авторизован (и при необходимости зарегистрирован) в системе
- name — полное имя этого пользователя
- role — роль пользователя (допустимые значения: 2 — обучающийся, 5 — преподаватель)
Допустимые параметры:
- url — URL страницы (без имени сервера, протокола, ведущих и завершающих слэшей), на которую нужно переадресовать пользователя после успешной авторизации, например, catalog, books/87914, info.
Возвращаемые данные внутри секции data:
- link — ссылка вида https://profspo.ru/api/login-or-register/AAAAAA/BBBBBB, которую необходимо сообщить пользователю с электронным адресом, переданным в запросе; при переходе по ссылке пользователь, если он не зарегистрирован в системе, регистрируется автоматически, в обоих случаях авторизуется в системе, а токен для ссылки уничтожается, так что ссылку повторно использовать не получится. Если пользователь является вновь зарегистрированным, то он перенаправляется не на главную страницу сайта, а на его профиль, где он может установить себе нужный пароль