PPLBandage Backend

Оглавление

• Base URL
• Ограничения по частоте запросов
• Ошибки
• Аутентификация
• Документация к API
• • Корневые эндпоинты API
• • Мастерская
• • Пользователи
• • Minecraft API
• • Auth

Введение

API PPLBandage — это RestFul API, позволяющий приложениям взаимодействовать с серверами и базой данных проекта.

Base URL

https://pplbandage.ru/api/v1

Ограничения по частоте запросов

Глобальное ограничение на все эндпоинты: 150rpm, однако оно может варьироваться в зависимости от конечного эндпоинта.

Эндпоинт	Ограничение по частоте запросов
GET /ping	Нет
GET /user/me/connections/minecraft/cache/purge	5rpm
POST /workshop	5rpm
GET /workshop/:id	Нет
GET /workshop/:id/info	Нет

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

Ошибки

Всего может возникнуть несколько типов ошибок:

Ошибки валидации

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

{
    "message": [
        "Массив ошибок валидации"
    ],
    "error": "Описание кода ошибки",
    "statusCode": 400
}

Общие ошибки

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

{
    "statusCode": 401,
    "message": "UNAUTHORIZED"
}

Так же в ошибках может быть поле message_ru, содержащее описание ошибки на русском.

Аутентификация

Аутентификация происходит через токены сессии.

Описание процесса аутентификации

Токены сессии должны передаваться в cookies запроса по ключу sessionId.
При создании запроса к API он проверяет валидность токена, время жизни которого равно 14 дням или двум неделям. Если со времени создания токена прошло более половины от его времени жизни, то бекенд обновляет токен и отправляет клиенту в Setcookie хедере.

Note

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

Запросы, не требующие строгой аутентификации обновлять токены не будут. Бекенд будет пытаться использовать переданный ему токен, пока у него не выйдет время жизни.

Warning

Бекенд не поддерживает выполнение параллельных запросов при обновлении токена. Клиенты должны сами позаботиться, чтобы запросы, подразумевающие обновление токена не выполнялись параллельно. В ином случае есть риск потерять текущую сессию.

Особенности работы

Комбинации запросов, требующих строгой аутентификации и нет могут вызвать неожиданное поведение!

Например, если выполняется сначала строгий запрос, а за ним нестрогий, последний может вернуть ошибку 401.
Пояснение:
Первый запрос приходит на сервер и возвращает с собой новый идентификатор сессии, который может быть не использован при выполнении последующих запросов. Данная проблема требует грамотного решения по предотвращению выполнения параллельных запросов и своевременного обновления файлов куки клиента.

Если не предотвращать параллельное выполнение запросов, то асинхронный бекенд может не обработать некоторые токены сессии, что приведет к неожиданному результату.

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

Если время жизни токена закончилось, бекенд вернёт HTTP код 401.
Все сессии связываются с fingerprint'ом текущего клиента, который представлен User-Agent хедером. Если запрос делается с другого User-Agent и по этому же токену, то он автоматически удаляется, возвращая HTTP код 401.