Общая информация¶

Введение¶

Данный раздел содержит описание программного интерфейса (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 может Администратор организации с помошью интерфейса работы с токенами организации.

Документация по API Календарь событий

Cправка