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

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