130 lines
2.6 KiB
Markdown
130 lines
2.6 KiB
Markdown
# API для разработчиков: параметры пользователя
|
||
|
||
Документ описывает операции для записи и чтения пользовательских параметров.
|
||
|
||
Текущие операции:
|
||
|
||
- `UpsertUserParam`
|
||
- `GetUserParam`
|
||
- `ListUserParams`
|
||
|
||
## 1. `UpsertUserParam`
|
||
|
||
### Запрос
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Успешный ответ
|
||
|
||
```json
|
||
{
|
||
"op": "UpsertUserParam",
|
||
"requestId": "param-upsert-001",
|
||
"status": 200,
|
||
"ok": true,
|
||
"payload": {
|
||
}
|
||
}
|
||
```
|
||
|
||
### Типовые ошибки
|
||
|
||
- `400 / BAD_FIELDS` — некорректные обязательные поля.
|
||
- `422 / BAD_SIGNATURE` — подпись не прошла проверку.
|
||
- `501 / DB_ERROR` — ошибка БД.
|
||
|
||
---
|
||
|
||
## 2. `GetUserParam`
|
||
|
||
### Запрос
|
||
|
||
```json
|
||
{
|
||
"op": "GetUserParam",
|
||
"requestId": "param-get-001",
|
||
"payload": {
|
||
"login": "alice",
|
||
"param": "display_name"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Успешный ответ
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
### Запрос
|
||
|
||
```json
|
||
{
|
||
"op": "ListUserParams",
|
||
"requestId": "param-list-001",
|
||
"payload": {
|
||
"login": "alice"
|
||
}
|
||
}
|
||
```
|
||
|
||
### Успешный ответ
|
||
|
||
```json
|
||
{
|
||
"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-модели ответа/запроса и должны передаваться именно в таком виде.
|