Інформаційна API [wiki.qeng.org]

Ця сторінка доступна тільки для перегляду. Ви можете продивитися вихідний текст, але не можете змінювати його. Якщо ви вважаєте, що це не вірно, зверніться до адміністратора.
{{indexmenu_n>40}}
===== Інформаційна API =====
В доменів є інформаційна API, за допомогою якої можна отримати інформацію про всі активні та майбутні ігри на домені у форматі JSON. Це корисно для розробки сторонніх сервісів, які дублюють інформацію про домен в інші місця (Telegram, сайти, тощо), і для власних [[uk: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,
        /* Час початку гри у форматі unix time */
        "end_time_f": 1658923200,
        /* Час завершення гри у форматі unix time */
        "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 бот =====
Отримати інформацію про зміни на сайті також можна за допомогою [[uk:info_api:tg_bot|Інформаційного Telegram бота]]