API для разработчиков: Общий формат запросов и ответов

Этот файл описывает не конкретные операции, а общий wire-контракт всего API сервера.

Здесь зафиксировано:

как выглядит любой запрос;
как выглядит любой успешный ответ;
как выглядит любой ответ с ошибкой;
какие поля являются обязательными для всех операций;
как клиент должен интерпретировать status, ok и payload.

Логика простая: сначала клиент и сервер договариваются о едином формате конверта, и только потом в остальных документах уже описываются конкретные методы и их поля.

1. Общий формат запроса

Все запросы по WebSocket используют один и тот же JSON-конверт:

{
  "op": "OperationName",
  "requestId": "req-001",
  "payload": {
  }
}

Поля

op — имя операции.
requestId — клиентский идентификатор запроса.
payload — объект параметров операции.

2. Общий формат успешного ответа

{
  "op": "OperationName",
  "requestId": "req-001",
  "status": 200,
  "ok": true,
  "payload": {
  }
}

3. Общий формат ответа с ошибкой

{
  "op": "OperationName",
  "requestId": "req-001",
  "status": 400,
  "ok": false,
  "error": "BAD_REQUEST",
  "message": "Human readable description",
  "payload": {
  }
}

4. Обязательные правила

Сервер возвращает op в каждом ответе.
Сервер возвращает requestId в каждом ответе без изменений.
Сервер возвращает status в каждом ответе.
Сервер возвращает ok в каждом ответе.
Сервер всегда возвращает payload как объект.
Даже при отсутствии данных сервер возвращает payload: {}.
ok находится на верхнем уровне ответа, а не внутри payload.

5. Правило интерпретации

Источник истины — status.

если status в диапазоне 200..299, то ответ успешный и ok должен быть true;
если status вне диапазона 200..299, то ответ ошибочный и ok должен быть false.

Запрещённые состояния:

status = 200 и ok = false;
status = 400 и ok = true.

6. Общие правила формата

Все строки подписи и challenge собираются в UTF-8.
Временные метки передаются как Unix time в миллисекундах.
Бинарные поля передаются строками Base64.
При ошибке error — это машинный код причины.
При ошибке message — человекочитаемое описание причины.

7. Общие коды ошибок

Ниже перечислены коды ошибок, которые не привязаны к одной конкретной операции и могут встречаться в разных местах API.

400 / EMPTY_JSON — клиент отправил пустое или полностью отсутствующее JSON-сообщение.
400 / NO_OP — в корневом объекте не передано поле op.
400 / UNKNOWN_OP — сервер не знает такую операцию.
400 / NO_PAYLOAD — в корневом объекте отсутствует payload.
400 / BAD_PAYLOAD — payload передан, но это не JSON-объект.
400 / BAD_REQUEST_FORMAT — JSON-конверт формально валиден, но поля операции не удалось распарсить в ожидаемый формат.
500 / INTERNAL_HANDLER_ERROR — в handler конкретной операции случилась непредвиденная серверная ошибка.
500 / INTERNAL_ERROR — произошла внутренняя ошибка на уровне общего JSON-процессора или другого серверного слоя.

Общее правило для dev/test этапа:

message в таких ошибках должен быть коротким, но полезным;
по возможности сервер добавляет тип исключения и краткую деталь причины;
это сделано для упрощения интеграционных тестов и отладки;
позже для production этот уровень детализации может быть уменьшен.

8. Источник истины по списку операций

Фактический список публичных WebSocket-операций берётся из:

shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java.

Если операция зарегистрирована в HANDLERS и REQUEST_TYPES, она считается доступной через JSON/WebSocket API. Общий актуальный индекс таких операций поддерживается в Dev_Docs/API/09_Operations_Index.md.

9. Короткое резюме

Запросы всегда идут как op + requestId + payload.
Ответы всегда идут как op + requestId + status + ok + payload.
Ошибки всегда возвращают ok: false, error, message, payload: {}.

6.1 KiB Raw Blame History Unescape Escape