Категории

Работа с API

C помощью API вы можете перенести курс с другой платформы на Stepik, настроить авторизацию, получение данных и т.д.

Stepik.org имеет REST API в формате JSON. Основные точки API перечислены на https://stepik.org/api/docs.

Документация и примеры использования API: https://github.com/StepicOrg/Stepic-API.

В stepik.org используется этот же API для работы веб-интерфейса (single-page application), поэтому все основные функции доступа и управления контентом поддерживаются через API. Некоторые редко используемые функции могут отсутствовать в API, поскольку они поддерживаются только через базовый веб-интерфейс платформы (не single-page application).

Flat

В API отсутствуют вложенные точки.

При запросе к API выдаётся не один объект, а список. Даже если запрашивался всего один объект (в таком случае в списке 1 элемент). Название списка совпадает с названием точки API.

Например, по запросу https://stepik.org/api/courses/1 выдаётся не один объект-курс, а список courses с одним объектом-курсом.

Pagination

Вся выдача GET происходит постранично с наличием в ответе словаря meta помимо запрашиваемого объекта. Получаемый JSON выглядит так: 

{
    "meta": {
        "page": 1,
        "has_next": true,
        "has_previous": false
    },
   "requested_objects": []
}

Словарь meta содержит информацию о текущей странице и наличие следующих / предыдущих страниц.

На примере это можно посмотреть по адресу:

https://stepik.org/api/courses (синоним https://stepik.org/api/courses?page=1), и далее на https://stepik.org/api/courses?page=2, https://stepik.org/api/courses?page=3 и т.д.

Обычный размер страницы – 20 элементов, но он может изменяться в зависимости от конкретной точки API.

Много ID в одном запросе к API

Если вы знаете ID объектов и хотите запросить их сразу одним запросом, можно использовать конструкцию следующего вида:

https://stepik.org/api/courses?ids[]=2&ids[]=67&ids[]=76&ids[]=70

Поддерживается всеми точками API. Пагинации в запросах с ids[] нет.

Не рекомендуется делать запросы с большим количеством ids[]. Подобные запросы, вероятнее всего, не будут приниматься сервером, так как получается слишком большой HTTP заголовок.

Side-Loading

Одним запросом к API иногда возвращаются сразу несколько связанных элементов. Например, зарегистрированному пользователю в https://stepik.org/api/courses помимо курсов будет также выдаваться информация об enrollments – его регистрациях на курс.

OAuth 2

Для использования Stepik.org API с правами существующего аккаунта на Stepik, нужна авторизация по OAuth2.

Для этого нужно создать приложение и получить ключи по ссылке https://stepik.org/oauth2/applications от профиля пользователя. Также в настройках приложения можно указать redirect_uri, Client type и Authorization grant type.

Ваши приложения можно найти по ссылке: https://stepik.org/oauth2/applications/.

Authorization endpoint (Authorization code, Implicit grant; требует наличия redirect_uri): https://stepik.org/oauth2/authorize/.

Token endpoint (Authorization code, Password и Client credentials): https://stepik.org/oauth2/token/.

Client credentials flow

Пример получения access token с использованием client credentials flow: 

curl -X POST -d "grant_type=client_credentials" -u "CLIENT_ID:CLIENT_SECRET" https://stepik.org/oauth2/token/

Ответ: 

{"access_token": "ACCESS_TOKEN", "scope": "read write", "expires_in": 36000, "token_type": "Bearer"}

Пример запроса с использованием access token: 

curl -H "Authorization: Bearer ACCESS_TOKEN" https://stepik.org/api/social-accounts?user=YOUR_USER_ID

Ответ: 

{"meta": {"page": 1, "has_next": false, "has_previous": false}, "social-accounts": [{"id": ..., "user": ..., "provider": ..., "uid": ...}]}

Authorization code flow

  1. В приложении надо указать grant type = autorization_code и redirect_uri;
  2. Переправить пользователя на страницу https://stepik.org/oauth2/authorize/?response_type=code&client_id=CLIENT_ID&redirect_uri=REDIRECT_URI;
  3. Пользователь аутентифицируется/регистрируется и разрешает приложению доступ к своему аккаунту (при необходимости можем не спрашивать разрешения);
  4. Происходит редирект на redirect_uri и передача CODE;
  5. Приложение запрашивает ACCESS_TOKEN: 
    curl -X POST -d "grant_type=authorization_code&code=CODE&redirect_uri=REDIRECT_URI" -u "CLIENT_ID:SECRET_ID" https://stepik.org/oauth2/token
  6. Приложение делает запросы от имени пользователя, добавляя заголовок:
    Authorization: Bearer ACCESS_TOKEN;
  7. Запрос https://stepik.org/api/stepics/1 возвращает в том числе и текущего пользователя.

Пример подключения с авторизацией по OAuth – https://gist.github.com/vyahhi/0c639c7a17c4fc828cc0.

Примеры внешних приложений, использующих Stepik.org API –