Введение

Принципы взаимодействия

Взаимодействие происходит по протоколу HTTPS (все запросы по HTTP будут перенаправлены на аналогичный HTTPS адрес).

Ответ возвращается в формате JSON.

Сессии реализуются через передачу cookie с именем sessionid; в случае, если в запросе cookie не указана, сервер создаст новую сессию и вернёт соответствующее значение cookie.

Примечание

Для защиты от CSRF (так как фунционал браузерной версии также построен на API), каждый POST запрос должен иметь cookie с именем csrftoken И либо POST параметр csrfmiddlewaretoken, либо заголовок X-CSRFToken, установленные в значение этой cookie. Значение для csrftoken cookie можно установить случайное (либо значение cookie будет установлено при 1-ом запросе к API). Значение csrftoken должно быть строкой из 64 символов (0-9,a-z).

Кроме того, необходимо передавать заголовок Referer: https://the-tale.org/.

Примеры запросов на логин к локальному серверу с использованием curl:

curl --insecure --referer "https://the-tale.org/" -b "sessionid=kwc2ngq02dilu56ti76nj21z18wzaghe; csrftoken=wxiefxk7i6kvkUeyi4jU2xO0B96RwvJc" -d "email=email@gmail.com&password=11111"  -H "X-CSRFToken: wxiefxk7i6kvkUeyi4jU2xO0B96RwvJc" "https://local.the-tale/accounts/auth/api/login?api_version=1.0&api_client=SASS-asas"

curl --insecure --referer "https://the-tale.org/" -b "sessionid=kwc2ngq02dilu56ti76nj21z18wzaghe; csrftoken=wxiefxk7i6kvkUeyi4jU2xO0B96RwvJc" -d "email=email@gmail.com&password=111111&csrfmiddlewaretoken=wxiefxk7i6kvUeyi4jU2xO0B96RwvJc" "https://local.the-tale/accounts/auth/api/login?api_version=1.0&api_client=SASS-asas"

Формат запроса

Адрес каждого метода имеет следующий формат:

https://the-tale.org/<адрес>?api_version=<версия>&api_client=<id клиента>&<параметры>
адрес:путь к методу
версия:версия метода (в стандартном формате через точку: 1.0, 1.1 и etc.)
id клиента:идентификатор клиентского приложения
параметры:аргументы, необходимые методу

Версионность

Каждый метод может иметь одну или несколько версий.

Старшая версия считается основной, остальные — устаревшими.

При обращении к устаревшей версии метода, в ответе будет присутствовать соответствующий флаг-индикатор.

В рамках одной версии метода гарантируется сохранение формата вызова.

В рамках одной версии метода гарантируется недеструктивное сохранение поведения (сторонние эффекты, коды возвращаемых ошибок).

В рамках одной версии метода возможно недеструктивное изменение формата возвращаемых данных (могут быть добавлены новые поля, без изменения структуры существовавших ранее).

Устаревшие версии методов будут удаляться из игры по прошествии времени, достаточного для перехода активных проектов на новые версии методов.

Идентификатор клиента

Передача идентификатора клиента необходима для сбора разработчиками статистики и возможности проведения разного рода «магических» действий в случае его неадекватного поведения.

Формат идентификатора: &lt;идентификатор программы&gt;-&lt;версия программы&gt;, в идентификаторе должен быть ровно 1 дефис.

Значение идентификатора выбирается пользователями API, регистрировать идентификатор нигде не требуется.

На наш взгляд, лучшим решением будет составление идентификатора из аббревиатуры названия клиента и версии (или даты) его сборки.

Неблокирующие операции

Некоторые запросы требуют длительного времени на свою обработку, поэтому для работы с ними реализован специальных механизм, позволяющий не блокировать выполнение клиента (и сервера) дожидаясь ответа на запрос. В описании таких операций это свойство отмечено отдельно.

Принцип работы неблокирующей операции:

  1. запрос клиента вызывает выполнение фоновой задачи на сервере;
  2. сервер возвращает ответ с информацией, по которой можно проверять статус выполнения задачи (со статусом «processing»);
  3. клиент периодически проверяет статус выполнения (желательно, не чаще раза в секунду), пока не получит сообщение о её завершении (или об ошибке);
  4. после этого операция считается выполненой.

Разница между «входом в игру» и «авторизацией в игре»

Для получения и изменения информации конкретного пользователя в API предусмотрено два метода: «вход в игру» и «авторизация в игре».

  1. «Вход в игру» требует от пользователя ввода логина и пароля. Это позволяет получать доступ к любым данным и производить любые действия от имени пользователя;
  2. «Авторизация в игре» не требует ввода логина и пароля. Она производится через выдачу пользователем разрешения на сайте игры. Приложение, получившее разрешение, не будет иметь доступ к наиболее важным данным и операциям пользователя (профилю, магазину и так далее).

Для выбора метода рекомендуется пользоваться следующим правилом: если Вы делаете приложение для себя или нескольких друзей (доверяющих вам), то можно использовать метод «вход в игру», во всех остальных случаях используйте «авторизацию в игре».

Формат ответа

Ответ на любой корректный запрос в случае корректной работы сервера возвращается с кодом 200.

{
  "depricated": true,                  // поле устанавливается, при обращении к устаревшей версии метода

  "status": "ok"|"error"|"processing", // ok — запрос обработан корректно
                                       // error — произошла ошибка
                                       // processing — запрошена неблокирующая операция, идёт обработка запроса
  "code": "error.code",                // строка — уникальный код ошибки (присутствует только в случае ошибки)
  "error": "сообщение",                // сообщение об ошибке для пользователя (присутствует только в случае ошибки)

  // если ошибка в данных, вводимых пользователем, вместо "error" в ответ вставляется "errors" с перечислением
  // идентификатор поля — имя параметра, в котором передавался ввод пользователя
  "errors": {"идентификатор поля": ["сообщение 1", "сообщение 2"]},

  "status_url": "url"                  // адрес проверки статуса неблокирующей операции (формат статуса такой же)

  "data": {},                          // запрошенные данные, в случае корректного выполнения запроса
                                       // дополнительная информация об ошибке, в случае некорректного выполнения запроса
}