152 lines
3.4 KiB
Markdown
152 lines
3.4 KiB
Markdown
# HTTP API
|
|
|
|
## Общие правила
|
|
|
|
API предназначен для iOS/macOS/watchOS и Android Balance.
|
|
|
|
Базовый URL задаётся клиентом и зависит от deployment environment.
|
|
|
|
JSON:
|
|
|
|
```http
|
|
Content-Type: application/json
|
|
```
|
|
|
|
Защищённые endpoints используют:
|
|
|
|
```http
|
|
Authorization: Bearer <access-token>
|
|
```
|
|
|
|
## Authentication
|
|
|
|
Основные операции:
|
|
|
|
```text
|
|
POST /v1/auth/register
|
|
POST /v1/auth/login
|
|
POST /v1/auth/logout
|
|
POST /v1/auth/refresh
|
|
```
|
|
|
|
### Register
|
|
|
|
Создаёт пользовательский аккаунт.
|
|
|
|
Input должен валидироваться сервером. Password никогда не хранится plaintext.
|
|
|
|
### Login
|
|
|
|
Проверяет credentials и создаёт authenticated session.
|
|
|
|
### Refresh
|
|
|
|
Принимает refresh credential и выдаёт новый access credential согласно текущей server-side session policy.
|
|
|
|
### Logout
|
|
|
|
Инвалидирует текущую session/refresh state согласно текущей реализации.
|
|
|
|
## Synchronization
|
|
|
|
Основной endpoint:
|
|
|
|
```text
|
|
POST /v1/sync
|
|
```
|
|
|
|
Логический request:
|
|
|
|
```json
|
|
{
|
|
"cursor": 123,
|
|
"deviceId": "UUID",
|
|
"changes": [],
|
|
"pull": true
|
|
}
|
|
```
|
|
|
|
Точная JSON schema должна оставаться совместимой с `ServerSync.swift` и Android `SyncRepository`.
|
|
|
|
## Change
|
|
|
|
Логическая форма:
|
|
|
|
```json
|
|
{
|
|
"entity": "transaction",
|
|
"id": "UUID",
|
|
"deleted": false,
|
|
"updatedAt": "2026-09-08T10:00:00Z",
|
|
"payload": {}
|
|
}
|
|
```
|
|
|
|
Поддерживаемые entity:
|
|
|
|
```text
|
|
transaction
|
|
category
|
|
budget
|
|
```
|
|
|
|
## Push
|
|
|
|
Client отправляет локальные изменения.
|
|
|
|
Server должен:
|
|
1. аутентифицировать пользователя;
|
|
2. проверить ownership/ID;
|
|
3. валидировать payload;
|
|
4. применить изменения;
|
|
5. создать server change entries;
|
|
6. вернуть результат и актуальную sync metadata.
|
|
|
|
Операция должна быть безопасна при retry.
|
|
|
|
## Pull
|
|
|
|
Client передаёт cursor.
|
|
|
|
Server возвращает изменения после этого cursor, включая deletions.
|
|
|
|
Если существует pagination, ответ должен содержать понятный признак продолжения и новый cursor/sequence.
|
|
|
|
## Ошибки
|
|
|
|
Рекомендуемый контракт:
|
|
|
|
```json
|
|
{
|
|
"error": {
|
|
"code": "invalid_request",
|
|
"message": "Human-readable safe message"
|
|
}
|
|
}
|
|
```
|
|
|
|
Не возвращать:
|
|
- SQL error;
|
|
- stack trace;
|
|
- password/token;
|
|
- filesystem paths;
|
|
- внутренние identifiers инфраструктуры.
|
|
|
|
## HTTP status semantics
|
|
|
|
Рекомендуемая семантика:
|
|
|
|
```text
|
|
200 OK — успешный request
|
|
201 Created — создание ресурса
|
|
400 Bad Request — malformed/invalid input
|
|
401 Unauthorized — missing/expired auth
|
|
403 Forbidden — resource belongs to another user
|
|
404 Not Found — resource/endpoint unavailable
|
|
409 Conflict — semantic conflict, если endpoint использует такую семантику
|
|
429 Too Many Requests — rate limit
|
|
500 Internal Server Error — internal failure
|
|
```
|
|
|
|
Конкретные status codes текущей реализации имеют приоритет над этой общей рекомендацией.
|