Информационная API [wiki.qeng.org]

Эта страница только для чтения. Вы можете посмотреть её исходный текст, но не можете его изменить. Сообщите администратору, если считаете, что это неправильно.
{{indexmenu_n>40}}
===== Информационная API=====
У доменов есть информационная API, с помощью которой можно полоучить инофрмацию обо всех активных и предстоящих играх на домене в формате JSON. Это полезно для разработки сторонних сервисов, дублирующих информацию о домене в другие места (Telegram, сайты и т.п.), и для собственных [[admin_main:domain_pages|страниц домена]], которые рисуют свою афишу.

==== Точка входа ====
**api_games_list.php**

Пример запроса:
[[https://game.qeng.org/api_games_list.php?v=2]]

==== Версия ====
Набор полей в ответе задаёт GET-параметр **v**.

  * **Без ''v''** — версия 1: ответ, который API отдавала всегда, вместе со списками команд (''teams'') и авторов (''authors''). Старые запросы с ''json=1'' — это она; менять её мы не будем, и параметр ''fields'' в ней не читается.
  * **''v=2''** — всё, кроме ''teams'' и ''authors''. Эти два списка собираются отдельными запросами к базе на каждую игру, а нужны далеко не всем: если они вам не нужны, ответ так получается заметно дешевле и быстрее.

Незнакомый номер версии считается последним известным, а не ошибкой.

==== Выбор полей ====
GET-параметр **fields** перечисляет через запятую, какие именно поля нужны. Работает начиная с ''v=2''.

  * Список задаёт набор **целиком**, а не добавку к набору версии.
  * Поле ''id'' есть в ответе всегда, просить его не нужно.
  * Порядок в запросе не важен — поля в ответе идут в своём обычном порядке.
  * Незнакомые имена просто пропускаются, ошибкой это не считается.

Пример: афише домена хватает названия, времени и рейтинга.
[[https://game.qeng.org/api_games_list.php?v=2&fields=name,start_time_f,end_time_f,rating,me]]

==== Формат результата ====
<code JavaScript>
[{Игра}, {Игра}, ...]
</code>
Здесь Игра - это объект следующего вида:
<code JavaScript>
{
        "id": 3287,
        /* ID игры */
        "start_time": "2022-07-25 15:00:00",
        /* Время начала игры в читабельном формате */
        "end_time": "2022-07-27 15:00:00",
        /* Время окончания игры в читабельном формате */
        "start_time_f": 1658750400,
        /* Время начала игры в формате unixtime*/
        "end_time_f": 1658923200,
        /* Время окончания игры в формате unixtime */
        "name": "QD10:  Операция болт или другие приключения гаечки",
        /* Название игры. Спецсимволы в формате HTML entity, например &quot; */
        "type": 1,
        /* Тип игры:
        0: Штурм
        1: Линейка
        2: Таймер
        */
        "kind": 1,
        /* Вид игры:
        0: other
        1: green
        2: yellow
        3: red
        4: virtual
        */
        "single": false,
        /* Одиночная или командная:
        false: Командная
        true: Одиночная
        */
        "description": "PS: следите за обновлениями.&lt;\/strong&gt;&lt;\/p&gt;\r\n",
         /* Описание игры*/
        "authors": [
            /* Список авторов. Только по запросу: fields=authors */
            {
                "uid": "2130",
                /* ID игрока */
                "username": "StelZ"
                /* Ник игрока */
            }
        ],
        "teams": [
            /* Список команд, подавших заявки на игру. Для одиночных игр - список игроков, подавших заявки.
               Только по запросу: fields=teams */
            {
                "id": "201",
                /* ID команды*/
                "name": "911 Team",
                /* Название команды*/
                "status": "0"
                /* Статус заявки:
                "0": Подали заявку
                "1": Приняты в игру
                "2": Приняты для теста
                */
            },
            {
                "id": "200",
                "name": "Nostra sQuadra",
                "status": "0"
            },
        ],
        "rating": {
            /* Оценка игры игроками - то же число, что на странице отзывов.
               null, если игру ещё никто не оценил. Только по запросу: fields=rating */
            "average": 4.5,
            /* Средняя оценка в звёздах, от 0.5 до 5 */
            "n": 12,
            /* Сколько игроков оценило */
            "n_reviews": 3
            /* Сколько из них написало отзыв */
        },
        "me": {
            /* Как дела в этой игре у того, кто спрашивает.
               null, если он не вошёл на сайт или в этой игре не участвует.
               Только по запросу: fields=me */
            "team_id": 201,
            /* Последняя активная команда: та, за которую он в этой игре играл
               последний раз. В одиночной игре это сам игрок, и тут его ID */
            "team_name": "911 Team",
            /* Её название, а в одиночной игре - имя самого игрока */
            "score": 340,
            /* Баллы этой команды - та же сумма, что игрок видит у себя в игре:
               с бонусами и штрафами. Может быть отрицательной */
            "status": "playing"
            /* Как далеко она в игре зашла:
            "playing": есть задание в работе
            "finished": в игре была, заданий в работе не осталось
            "not_started": заявка есть, игру ещё не начинала
            */
        }
    }
</code>

Поле ''me'' считается для того, кто прислал запрос, поэтому со страницы домена его надо запрашивать обычным ''fetch()'' с того же домена — тогда браузер сам приложит к запросу куки, и движок узнает игрока. Ответ с этим полем кэшировать нельзя, и заголовки об этом движок ставит сам.

Состояния ''"finished"'' по времени тут не бывает: список отдаёт только игры, которые ещё не кончились.

===== Информационный Telegram бот =====
Получить информацию об изменениях на сайте также можно с помощью [[info_api:tg_bot|Информационного Telegram бота]]