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.