API

Unixgram API

Застосунок розмовляє із сервером через звичайний HTTP API. Він однаковий для вебу й для нативних клієнтів і влаштований так, що відповідь можна розібрати, не знаючи заздалегідь, що саме пішло не так.

Один конверт на всі відповіді

Успіх і помилка відрізняються полем success, а не набором ключів. Клієнту не треба вгадувати форму відповіді за кодом стану: вона завжди розбирається однаково.

// успіх
{ "success": true, "data": { "post": { "id": "..." } } }

// помилка
{ "success": false,
  "error": { "code": "VALIDATION_ERROR", "message": "...", "details": [] } }

Захист запитів, що змінюють дані

Кожен запит, який змінює дані, зобов'язаний принести заголовок x-csrf-token, що збігається з виданою раніше cookie. Схема double-submit із підписом HMAC: підробити заголовок, не маючи cookie, неможливо, а прочитати cookie з іншого origin браузер не дасть.

GET  /api/auth/csrf        → видає cookie + токен
POST /api/social/posts
     x-csrf-token: <токен із cookie>
     content-type: application/json

Обмеження частоти

Чутливі маршрути — вхід, реєстрація, відновлення пароля, надсилання кодів — обмежені за частотою на джерело. Перевищення повертає 429 і заголовок із часом, через який можна повторити.

Події реального часу

Потік подій доставляється через UnixProto, а за його недоступності — звичайними Server-Sent Events на /api/realtime/events. Імена подій утворюють закритий список: нова подія додається одночасно на сервері та на клієнті, інакше її буде мовчки відкинуто.

message:new     нове повідомлення в чаті
post:deleted    допис видалено
feed:new        нові дописи у стрічці
stars:balance   змінився баланс зірок

Публічні ключі доступу та документація щодо методів готуються. Наразі API розрахований на власні клієнти Unixgram.