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, которую необходимо сообщить пользователю с электронным адресом, переданным в запросе; при переходе по ссылке пользователь, если он не зарегистрирован в системе, регистрируется автоматически, в обоих случаях авторизуется в системе, а токен для ссылки уничтожается, так что ссылку повторно использовать не получится. Если пользователь является вновь зарегистрированным, то он перенаправляется не на главную страницу сайта, а на его профиль, где он может установить себе нужный пароль