Text Content
ДОКУМЕНТАЦИЯ В ФОРМАТЕ SWAGGER
Документация доступна по адресу
http://aisgu.khv.gov.ru/dnevnik/partners/swagger/ui/index
ОБЩАЯ ИНФОРМАЦИЯ
Дневник.ру предоставляет набор API для создания сторонних приложений и
интеграции внешних сервисов. Через API сторонние приложения могут получить
доступ к общим данным сервиса, а также к личным данным пользователя.
Взаимодействие с API происходит по протоколу HTTPS в соответствии с
архитектурным стилем REST.
Объекты, доступные через API, представлены в виде ресурсов, например, user,
school, lesson. Каждый ресурс имеет уникальный URL, например,
http://aisgu.khv.gov.ru/dnevnik/v1/users/386. Работа с ресурсом происходит
посредством отправки HTTP запросов с соответствующим семантике действия
HTTP-методом. Все ресурсы представляются в формате JSON. Параметры, передаваемые
в теле POST запросов, необходимо формировать также в виде JSON объектов, а также
проставлять HTTP заголовок Content-Type: application/json.
Например,
* GET http://aisgu.khv.gov.ru/dnevnik/v1/users/634 - получение профиля
пользователя
* POST http://aisgu.khv.gov.ru/dnevnik/v1/messages - отправление личного
сообщения
* DELETE http://aisgu.khv.gov.ru/dnevnik/v1/marks/1333 - удаление оценки
Ряд ресурсов содержит ФИО юзера и аватар. Эти данные являются служебными и
предназначены только для приложений с доступом к персональным данным юзера. Для
остальных приложений соответствующие поля не возвращаются.
АВТОРИЗАЦИЯ
Для выполнения большинства действий через API приложению необходимо получить
токен доступа. Для авторизации сторонних приложений используется фреймворк
OAuth2.
Каждый токен привязан к конкретному пользователю и приложению,
зарегистрированному в системе.
После того как токен доступа получен, приложение должно включать его в каждый
запрос к API в качестве параметра URL access_token или заголовка HTTP
Access-Token.
РЕГИСТРАЦИЯ ПРИЛОЖЕНИЯ
Для регистрации приложения необходимо заполнить форму для разработчиков. После
этого с вами свяжутся и предоставят идентификатор приложения и пароль для
авторизации.
ПРОЦЕДУРА ПОЛУЧЕНИЯ ТОКЕНА ДОСТУПА
1. Стороннее приложение перенаправляет пользователя по адресу
https://login.dnevnik.ru/oauth2?response_type=<token|code>&client_id=<client_id>&scope=<scope>&redirect_uri=<redirect_uri>&state=<state>.
Параметры запроса
* response_type тип ответа, который требуется от oauth2-сервера
* token - токен доступа, будет передан в составе фрагмента (добавляемого к
URI после символа #)
* code - код запроса токена, будет передан в виде query-параметра
(добавляемого к URI после символа ?) Код запроса токена используется в
случае, когда передача самого токена в составе фрагмента невозможна или
нежелательна. В этом случае получить токен можно с помощью запроса к
API.
* client_id идентификатор приложения, полученный при регистрации.
* scope набор прав доступа, необходимых приложению (перечисляются через
запятую)
* redirect_uri адрес редиректа
* state опциональный произвольный параметр состояния для передачи информации
на redirect_uri.
2. После отказа или подтверждения пользователя происходит редирект на указанный
адрес.
* Если пользователь разрешил приложению доступ к своим личным данным, набор
передаваемых OAuth-сервером параметров зависит от значения response_type.
* для значения token происходит редирект на
redirect_uri#access_token=<access_token>&state=<state>
* для значение code происходит редирект на
redirect_uri?code=<code>&;state=<state>
* Если пользователь отказал приложению в доступе, то OAuth-сервер добавляет
к redirect_uri параметр error=access_denied (а также параметр state, если
он был указан в исходном запросе). В случае ошибки в запросе авторизации,
при редиректе в параметре error также передаётся код ошибки:
* invalid_request - неверный запрос
* unauthorized_client - неверный идентификатор приложения
* invalid_scope - неверный набор прав доступа
3. Если был запрошен код, то его необходимо обменять на токен доступа.
ПРАВА ДОСТУПА ДЛЯ ПРИЛОЖЕНИЙ
* CommonInfo - личные данные
* ContactInfo - контактная информация
* FriendsAndRelatives - список друзей и родственников
* EducationalInfo - информация о школе и успеваемости
* SocialInfo - список групп и событий
* Files - файлы пользователя
* Wall - стена
* Messages - личные сообщения
ТИПЫ ОШИБОК
Если при обработке запроса произошла ошибка, то ответ будет содержать код
состояния 4xx или 5xx , а тело ответа - объект ApiError с ошибкой одного из
следующих типов:
* InvalidRequest - неверный запрос
* ParameterInvalid - неверное значение одного из параметров
* ApiResourceUnavailable - ресурс не существует
* ApiMethodNotSupported - метод не поддерживается для этого ресурса
* ApiRequestLimit - превышен лимит запросов для данного токена
* ApiServerError - ошибка на сервере
* ApiHttpsRequired - ресурс доступен только через https
* AuthorizationInvalidToken - неверный или неактивный токен
* AuthorizationTokenRequired - для доступа к ресурсу нужна авторизация
* AuthorizationOutOfScope - токен содержит недостаточно прав доступа
* AuthorizationNotOwner - текущий пользователь не является владельцем ресурса
* AuthorizationOwnerForbidden - данный запрос запрещён владельцем ресурса
* AuthorizationSystemForbidden - данный запрос запрещён правилами доступа
системы
