diff --git a/source/api.rst b/source/api.rst new file mode 100644 index 0000000..8770110 --- /dev/null +++ b/source/api.rst @@ -0,0 +1,147 @@ +Ely.by API (симуляция Mojang API) +--------------------------------- + +Здесь приведена информация об API, совместимом с функционалом `Mojang Api `_. Обращаем ваше +внимание на то, что это не полноценное API Ely.by, а только набор дополнительных запросов, реализованных на базе нашего +`сервера авторизации `_. + +Заметки +======= + +* API не имеет ограничения на количество запросов. У нас есть просто настроенный fail2ban, который будет банить особо + надоедливых клиентов. Такие дела. + +Запросы +======= + +В этой секции будут описаны запросы и их же варианты для Mojang API. Все запросы выполняются на базовый url +``https://authserver.ely.by``. + +UUID по нику на время +~~~~~~~~~~~~~~~~~~~~~ + +Данный запрос позволяет узнать UUID пользователя по его нику на указанный момент времени. Время задаётся через GET +параметр at с unitx timestamp. + +.. note:: На самом деле Ely.by пока не запоминает период смены ника и не обращает внимание на этот запрос. Тем не менее + параметр в будущем будет дореализован. + +.. function:: GET /api/users/profiles/minecraft/{username} + + Где username - искомый ник пользователя. Он может быть передан в любом регистре (В Mojang API только строгое + совпадение). + + Обратите так же внимание, что параметры legacy и demo никогда не будут возвращены, т.к. эти параметры не имеют в Ely + альтернативы и специфичны только для сервисов Mojang. + +В случае успешного запроса вы получите следующий ответ сервера: + +.. code-block:: javascript + + { + "id": "ffc8fdc95824509e8a57c99b940fb996", + "name": "ErickSkrauch" + } + +В случае, если переданный ник не будет найден, вы получите ответ с 204 статусом и пустым телом. + +Никнейм по UUID + история изменений +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Данный запрос позволяет узнать все ники, использованные пользователем по его UUID. + +.. function:: GET /api/user/profiles/{uuid}/names + + Где uuid - валиданый UUID. Валидным будет считаться UUID, написанный через дефисы или без них. В случае передачи + невалидной строки, будет возвращён IllegalArgumentException_ с сообщением ``"Invalid uuid format."``. + +В случае успешного запроса вы получите следующий ответ сервера: + +.. code-block:: javascript + + [ + { + "name": "Admin" + }, + { + "name": "ErickSkrauch", + "changedToAt": 1440707723000 + } + ] + +.. note:: Т.к. на Ely.by не реализован алгоритм запоминания момента смены ника, будет возвращаться только 1 элемент. + Чуть позже мы добавим полноценную поддержку запоминания момента смены ника. + +В случае, если переданный UUID не будет найден, вы получите ответ с 204 статусом и пустым телом. + +Список никнеймов в их UUID +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Этот запрос позволяет запросить список UUID пользователей по списку ников. + +.. function:: POST /api/profiles/minecraft + + В теле запроса или POST параметрах необходимо передать валидный JSON массив искомых ников. + + В массиве должно быть не более 100 ников, в противном случае будет возвращён IllegalArgumentException_ с сообщением + ``"Not more that 100 profile name per call is allowed."``. В случае, если переданная строка окажется невалидным + JSON объектом, будет возвращёно это же исключение, только с текстом ``"Passed array of profile names is an invalid + JSON string."``. + + Пример тела запроса: + + .. code-block:: javascript + + ["ErickSkrauch", "EnoTiK", "KmotherfuckerF"] + +В случае успешного запроса вы получите следующий ответ сервера: + +.. code-block:: javascript + + [ + { + "id": "ffc8fdc95824509e8a57c99b940fb996", + "name": "ErickSkrauch" + }, + { + "id": "b8407ae8218658ef96bb0cb3813acdfd", + "name": "EnoTiK" + }, + { + "id": "39f42ba723de56d98867eabafc5e8e91", + "name": "KmotherfuckerF" + } + ] + +Данные возвращаются в том же порядке, в каком и были запрошены. + +В случае, если один из переданных никнеймов не найден в базе данных, для него не будет возвращено значения (он будет +просто пропущен). Учитывайте эту ситуацию при парсинге ответа. + +Запрос информации о профиле по UUID +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +См. `запрос профиля для сервера авторизации `_. + +Возможные ошибки +================ + +.. _IllegalArgumentException: + +IllegalArgumentException +~~~~~~~~~~~~~~~~~~~~~~~~ + +Данная ошибка возникает при попытке передать на сервер данные в неправильном формате. + +Пример подобной ошибки: + +.. code-block:: javascript + + // Пример ошибки при неправильном формате UUID + { + "error": "IllegalArgumentException", + "errorMessage": "Invalid uuid format." + } + +``errorMessage`` не всегда совпадает с таковым у Mojang, но в основном это касается только специфичных только для Ely +ошибок. Оригинальные же запросы и ожидаемые от них ошибки повторяют тексты Mojang. diff --git a/source/index.rst b/source/index.rst index f956f77..931d7ae 100644 --- a/source/index.rst +++ b/source/index.rst @@ -21,4 +21,5 @@ skin-system minecraft-auth oauth + api diff --git a/source/minecraft-auth.rst b/source/minecraft-auth.rst index 60f0af8..8d8831c 100644 --- a/source/minecraft-auth.rst +++ b/source/minecraft-auth.rst @@ -222,10 +222,13 @@ accessToken. Вам остаётся только заменить пути вн Тем не менее, описанный ниже запрос актуален только для Minecraft 1.7.6+, когда для загрузки скинов стала использоваться так же authlib. +.. _profile-request: + .. function:: GET /session/profile/{uuid} Запрос на этот URL выполняется клиентом в одиночной игре на локальном сервере (созданном посредством самой игры). - В URL передаётся UUID пользователя, с которым был запущен клиент, а в ответ получается информация о текстурах игрока. + В URL передаётся UUID пользователя, с которым был запущен клиент, а в ответ получается информация о текстурах игрока + в таком же формате, как и при hasJoined запросе. Готовые библиотеки authlib ==========================