Общая информация¶
Введение¶
Данный раздел содержит описание программного интерфейса (Application programming interface - API) к сервису портала. API - это инструмент для разработчиков, который позволяет интегрировать портал с другими сайтами, порталами, информационными системами вузов. Описание предназначено для разработчиков, заинтересованных в получении программного доступа к функциям. Предполагается, что разработчик уже знаком с возможностями портала.
Описание API отображается при помощи Swagger и доступно по ссылке.
Swagger делает описание интерактивным и позволяет генерировать код клиентской части. Например, генерация кода клиентской части доступна при помощи ресурса https://editor.swagger.io/.
Версионирование¶
Все разделы API поддерживают версионирование. У каждой версии есть определенный идентификатор (v1, v2 и т. п.). При выходе новой версии API предыдущая версия продолжает работать для поддержания обратной совместимости.
Если вы начинаете работу с API, используйте самую последнюю версию. Если вы уже используете предыдущие версии API, рекомендуем постепенно переходить на последнюю, т. к. поддержка старых версий ограничена во времени.
При формировании запроса к API всегда указывайте версию, с которой вы хотите работать.:
https://api.lomonosov-msu.ru/api/v1/...
https://api.lomonosov-msu.ru/api/v2/...
Ресурсы¶
API построен по REST-принципам.
Все, чем можно управлять через API, представлено в виде ресурсов: календарь, мероприятие, пользователь и т. д.
То есть ресурс — это некая целостная часть системы, с которой можно работать:
читать содержимое и текущее состояние ресурса (GET);
изменять содержимое и состояние и записывать его в ресурс (PUT);
удалять ресурс (DELETE);
выполнять действия ― например, добавлять новые элементы в список (POST).
У каждого ресурса есть свой уникальный URL. Все действия выполняются соответствующими методами протокола HTTP на URL’ы ресурсов.
Например, чтобы получить информацию о мероприятии, необходимо сделать GET-запрос на URL соответствующего ресурса.
Вызов методов¶
Запрос к сервису задается в следующем формате:
<тип_метода> https://api.lomonosov-msu.ru/api/<версия>/<раздел_API>/<имя_метода>/<параметры>
<тип метода> ― GET, POST, PUT или DELETE.
<раздел_API> ― название раздела API, в котором выполняется действие.
<версия> ― номер текущей версии API.
<имя_метода> ― URL ресурса, над которым выполняется действие.
<параметры> ― обязательные и необязательные параметры запроса.
API возвращает ответы в кодировке UTF-8. Ответы имеют формат JSON, что определяется при вызове методов с помощью HTTP-заголовка Accept: application/json.
Авторизация¶
Для использования API необходимо получить авторизационный токен у Администратора организации. Токен необходимо передавать для каждого метода в HTTP-заголовке Organization-Token.
Пример HTTP-заголовка:
GET /api/v1/organization/event-calendars HTTP/1.1
Host: api.lomonosov-msu.ru
Organization-Token: 05dd3dd84ff948fdae2bc4fb91f13e22bb1f289ceef0037
Accept: application/json
Если метод API вызван без токена или в запросе передан недействительный токен, сервер возвращает HTTP-статус 401 Unauthorized.
Квотирование¶
С целью обеспечения максимального уровня доступности сервиса, предусмотрено ограничение на интенсивность запросов к API со стороны пользователя. Ограничение работает по следующему правилу - число запросов с одним Organization-Token в сутки не должно превышать 5000.
В случаее превышения ограниченя происходит автоматическая блокировка Organization-Token. Разблокировать данный Organization-Token может Администратор организации с помошью интерфейса работы с токенами организации.