From 546223f15806bf15257e70f06f4991ecf11a1fd7 Mon Sep 17 00:00:00 2001 From: ErickSkrauch Date: Fri, 28 Aug 2015 22:26:32 +0300 Subject: [PATCH] =?UTF-8?q?=D0=94=D0=BE=D0=B1=D0=B0=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B0=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5=D0=BD=D1=82?= =?UTF-8?q?=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BF=D0=BE=20Ely.by=20API=20=D0=B4?= =?UTF-8?q?=D0=BB=D1=8F=20=D1=81=D0=B5=D1=80=D0=B2=D0=B5=D1=80=D0=B0=20?= =?UTF-8?q?=D0=B0=D0=B2=D1=82=D0=BE=D1=80=D0=B8=D0=B7=D0=B0=D1=86=D0=B8?= =?UTF-8?q?=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- source/api.rst | 147 ++++++++++++++++++++++++++++++++++++++ source/index.rst | 1 + source/minecraft-auth.rst | 5 +- 3 files changed, 152 insertions(+), 1 deletion(-) create mode 100644 source/api.rst 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 ==========================