SHiNE-server/Dev_Docs/API/10_User_Params_API.md

API для разработчиков: параметры пользователя

Документ описывает операции для записи и чтения пользовательских параметров.

Текущие операции:

• UpsertUserParam
• GetUserParam
• ListUserParams

1. UpsertUserParam

Запрос

{
  "op": "UpsertUserParam",
  "requestId": "param-upsert-001",
  "payload": {
    "login": "alice",
    "param": "display_name",
    "time_ms": 1774700000123,
    "value": "Alice",
    "device_key": "BASE64_DEVICE_PUBLIC_KEY",
    "signature": "BASE64_SIGNATURE"
  }
}

Успешный ответ

{
  "op": "UpsertUserParam",
  "requestId": "param-upsert-001",
  "status": 200,
  "ok": true,
  "payload": {
  }
}

Типовые ошибки

• 400 / BAD_FIELDS — некорректные обязательные поля.
• 422 / BAD_SIGNATURE — подпись не прошла проверку.
• 501 / DB_ERROR — ошибка БД.

---

2. GetUserParam

Запрос

{
  "op": "GetUserParam",
  "requestId": "param-get-001",
  "payload": {
    "login": "alice",
    "param": "display_name"
  }
}

Успешный ответ

{
  "op": "GetUserParam",
  "requestId": "param-get-001",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "alice",
    "param": "display_name",
    "time_ms": 1774700000123,
    "value": "Alice",
    "device_key": "BASE64_DEVICE_PUBLIC_KEY",
    "signature": "BASE64_SIGNATURE"
  }
}

Если параметр не найден, сервер возвращает 404 с пустым payload; отдельный прикладной код ошибки текущий handler не задаёт.

---

3. ListUserParams

Запрос

{
  "op": "ListUserParams",
  "requestId": "param-list-001",
  "payload": {
    "login": "alice"
  }
}

Успешный ответ

{
  "op": "ListUserParams",
  "requestId": "param-list-001",
  "status": 200,
  "ok": true,
  "payload": {
    "login": "alice",
    "params": [
      {
        "login": "alice",
        "param": "display_name",
        "time_ms": 1774700000123,
        "value": "Alice",
        "device_key": "BASE64_DEVICE_PUBLIC_KEY",
        "signature": "BASE64_SIGNATURE"
      }
    ]
  }
}

Примечание

Имена JSON-полей time_ms и device_key сейчас соответствуют Java-модели ответа/запроса и должны передаваться именно в таком виде.