Стабільність і сумісність

Чесно про те, на що можна спиратися, а на що ні, якщо ви пишете власний клієнт.

Версії API поки немає

Сервер не повідомляє версію протоколу, і формальних гарантій сумісності немає. Назва події чи форма відповіді можуть змінитися з будь-яким комітом.

Практичний висновок: прив'яжіться до конкретної версії сервера, який ви розгортаєте, і перечитуйте цю документацію після оновлення. Оскільки типовий сценарій — самохостинг зі свого форку, момент оновлення контролюєте ви самі.

Як зробити клієнт стійкішим

Кілька звичок, які здешевлюють оновлення.

Визначайте можливості, а не версію. GET /api/public/config каже, у якому режимі сервер. Гілкуйтеся по streamMode, musicSource, radioHostsMode, а не по припущеннях про конфігурацію.

Не розбирайте текст повідомлень. Локалізовані рядки змінюються з кожним уточненням перекладу. Там, де є поле code, гілкуйтеся по ньому — див. Формат повідомлень.

Ігноруйте невідомі поля. У sync та інших відповідях з часом додаються поля. Клієнт, який падає на незнайомому ключі, зламається на першому ж оновленні.

Не покладайтеся на порядок. Порядок треків у playlist осмислений, а от порядок ключів в об'єктах — ні.

Готуйтеся до зникнення події. Подій уже позбувалися: trackEnd і trackDuration прибрали, коли просування черги зробили суто серверним. Клієнт має спокійно переживати те, що подія більше не приходить.

Що змінюється найрідше

Ці частини протоколу — несучі, і навряд чи зміняться без вагомої причини:

• подія sync як єдине джерело стану радіо;
• обмін listener_init → listener_uid → /api/audio-key;
• вимога двох токенів для аудіо;
• те, що серверні повідомлення приходять об'єктом з усіма локалями.

Що може змінитися

• Склад полів у sync — поля додаються.
• Адмінські ендпоінти й події: їх найбільше, і вони найактивніше змінюються.
• XOR-обгортка ресурсів — це обфускація, а не безпека, тож механізм цілком може бути замінений на щось інше.

Якщо ви розгортаєте сервер для інших

Варто зафіксувати версію самому: додайте поле версії у відповідь /api/public/config і збільшуйте його при кожній ламкій зміні. Тоді сторонні клієнти зможуть чесно сказати користувачеві «цей сервер новіший за мене» замість того, щоб мовчки поводитися дивно.