docs/source/api.rst

Ely.by API (симуляция Mojang API)
---------------------------------

Здесь приведена информация об API, совместимом с функционалом `Mojang Api <http://wiki.vg/Mojang_API>`_. Обращаем ваше
внимание на то, что это не полноценное API Ely.by, а только набор дополнительных запросов, реализованных на базе нашего
`сервера авторизации </minecraft-auth.html>`_.

Заметки
=======

* 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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

См. `запрос профиля для сервера авторизации <minecraft-auth.html#profile-request>`_.

Возможные ошибки
================

.. _IllegalArgumentException:

IllegalArgumentException
~~~~~~~~~~~~~~~~~~~~~~~~

Данная ошибка возникает при попытке передать на сервер данные в неправильном формате.

Пример подобной ошибки:

.. code-block:: javascript

   // Пример ошибки при неправильном формате UUID
   {
     "error": "IllegalArgumentException",
     "errorMessage": "Invalid uuid format."
   }

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