# Update Server API

Этот документ описывает текущий публичный HTTP API сервиса. Его можно передать
клиентскому приложению или агенту, который встраивает автообновление.

Примеры ниже используют:

```text
Base URL: https://updates.example.com
API key:  upsk_replace_me
Project:  desktop-app
```

В реальной интеграции замени `Base URL`, API key и `project_slug` на свои
значения.

## Общая модель

Update Server хранит проекты и релизы:

- `project` - приложение, продукт или канал обновлений;
- `release` - загруженный файл обновления внутри проекта;
- `api key` - клиентский ключ доступа к API.

Администратор работает через web UI:

```text
/admin
/admin/projects
/admin/api-keys
```

Клиентские приложения работают через JSON API:

```text
/api/v1
```

На текущий момент JSON API предназначен для чтения и скачивания обновлений.
Создание проектов, загрузка релизов и создание API keys выполняются через admin
web UI, а не через публичный JSON API.

## Авторизация

Защищенные endpoint'ы требуют bearer token:

```http
Authorization: Bearer <api_key>
```

Пример:

```bash
curl -i \
  -H "Authorization: Bearer upsk_replace_me" \
  https://updates.example.com/api/v1/projects
```

API key должен быть:

- активным;
- не истекшим по `expires_at`, если срок задан;
- с разрешением `can_download`;
- со scope, который разрешает доступ к нужному проекту.

Поддерживаемые scope modes:

```text
all_projects
project_allow_list
project_deny_list
tag_allow_list
tag_deny_list
```

Полный API key показывается в admin UI только один раз при создании. Сервер
хранит только hash ключа.

## Формат JSON

Все JSON-ответы возвращаются с:

```http
Content-Type: application/json; charset=utf-8
```

Поля времени возвращаются строкой в формате RFC3339/RFC3339Nano, например:

```json
"created_at": "2026-06-11T10:15:30Z"
```

Относительные URL в ответах, например `download_url`, нужно склеивать с
`Base URL` клиента.

## Health Check

### GET /healthz

Публичная проверка готовности HTTP-сервера и SQLite.

```bash
curl -i https://updates.example.com/healthz
```

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

```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
```

```json
{
  "database": "ok",
  "service": "Update Server",
  "status": "ok",
  "timestamp": "2026-06-11T10:15:30Z"
}
```

Если база недоступна:

```http
HTTP/1.1 503 Service Unavailable
```

```json
{
  "database": "unavailable",
  "error": "database ping failed",
  "service": "Update Server",
  "status": "degraded",
  "timestamp": "2026-06-11T10:15:30Z"
}
```

## API Index

### GET /api/v1

Публичный JSON-index текущей версии API. Авторизация не нужна.

```bash
curl -i https://updates.example.com/api/v1
```

Ответ:

```json
{
  "auth": {
    "header": "Authorization: Bearer <api_key>",
    "type": "bearer"
  },
  "routes": [
    {
      "description": "List active projects accessible to the API key.",
      "method": "GET",
      "path": "/api/v1/projects"
    },
    {
      "description": "Get the latest active release metadata for an accessible project.",
      "method": "GET",
      "path": "/api/v1/projects/{projectSlug}/releases/latest"
    },
    {
      "description": "Get release metadata for an accessible release.",
      "method": "GET",
      "path": "/api/v1/releases/{releaseID}"
    },
    {
      "description": "Download the private artifact for an accessible release.",
      "method": "GET",
      "path": "/api/v1/releases/{releaseID}/download"
    }
  ],
  "service": "Update Server",
  "status": "client-api-ready",
  "version": "v1"
}
```

## List Accessible Projects

### GET /api/v1/projects

Возвращает активные проекты, доступные текущему API key.

Требует:

```http
Authorization: Bearer <api_key>
```

Пример:

```bash
curl -i \
  -H "Authorization: Bearer upsk_replace_me" \
  https://updates.example.com/api/v1/projects
```

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

```json
{
  "projects": [
    {
      "id": 1,
      "name": "Desktop App",
      "slug": "desktop-app",
      "description": "Primary desktop updater stream.",
      "latest_release_url": "/api/v1/projects/desktop-app/releases/latest"
    }
  ]
}
```

Если доступных проектов нет:

```json
{
  "projects": []
}
```

## Get Latest Release

### GET /api/v1/projects/{projectSlug}/releases/latest

Возвращает latest active release для активного и доступного проекта.

Latest release выбирается по:

```text
created_at DESC, id DESC
```

Пример:

```bash
curl -i \
  -H "Authorization: Bearer upsk_replace_me" \
  https://updates.example.com/api/v1/projects/desktop-app/releases/latest
```

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

```json
{
  "project": {
    "id": 1,
    "name": "Desktop App",
    "slug": "desktop-app",
    "description": "Primary desktop updater stream.",
    "latest_release_url": "/api/v1/projects/desktop-app/releases/latest"
  },
  "release": {
    "id": 2,
    "version": "1.1.0",
    "build": "build-2",
    "filename": "desktop-app-1.1.0.zip",
    "checksum_sha256": "4bf5122f344554c53bde2ebb8cd2b7e3d1600ad631c385a5d7c6e64b2f7110b2",
    "size_bytes": 12345678,
    "content_type": "application/zip",
    "release_notes": "Improved desktop rollout.",
    "created_at": "2026-06-11T10:15:30Z",
    "metadata_url": "/api/v1/releases/2",
    "download_url": "/api/v1/releases/2/download"
  }
}
```

Если проект не существует, архивирован или недоступен этому key:

```http
HTTP/1.1 404 Not Found
```

```json
{
  "error": "resource not found"
}
```

Если проект доступен, но активных релизов нет:

```http
HTTP/1.1 404 Not Found
```

```json
{
  "error": "release not found"
}
```

## Get Release Metadata

### GET /api/v1/releases/{releaseID}

Возвращает metadata релиза по ID. Релиз должен быть активным, его проект должен
быть активным, и текущий API key должен иметь доступ к проекту релиза.

Пример:

```bash
curl -i \
  -H "Authorization: Bearer upsk_replace_me" \
  https://updates.example.com/api/v1/releases/2
```

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

```json
{
  "project": {
    "id": 1,
    "name": "Desktop App",
    "slug": "desktop-app",
    "description": "Primary desktop updater stream.",
    "latest_release_url": "/api/v1/projects/desktop-app/releases/latest"
  },
  "release": {
    "id": 2,
    "version": "1.1.0",
    "build": "build-2",
    "filename": "desktop-app-1.1.0.zip",
    "checksum_sha256": "4bf5122f344554c53bde2ebb8cd2b7e3d1600ad631c385a5d7c6e64b2f7110b2",
    "size_bytes": 12345678,
    "content_type": "application/zip",
    "release_notes": "Improved desktop rollout.",
    "created_at": "2026-06-11T10:15:30Z",
    "metadata_url": "/api/v1/releases/2",
    "download_url": "/api/v1/releases/2/download"
  }
}
```

Если `releaseID` не число:

```http
HTTP/1.1 400 Bad Request
```

```json
{
  "error": "invalid release id"
}
```

Если релиз не существует, архивирован или недоступен:

```http
HTTP/1.1 404 Not Found
```

```json
{
  "error": "resource not found"
}
```

## Download Release Artifact

### GET /api/v1/releases/{releaseID}/download

Скачивает приватный artifact релиза. Скачивание проходит через приложение, чтобы
сервер мог проверить API key, permission и project scope.

Пример:

```bash
curl -L \
  -H "Authorization: Bearer upsk_replace_me" \
  -o desktop-app-1.1.0.zip \
  https://updates.example.com/api/v1/releases/2/download
```

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

```http
HTTP/1.1 200 OK
Content-Disposition: attachment; filename=desktop-app-1.1.0.zip
Content-Type: application/zip
X-Content-Type-Options: nosniff
```

Body ответа - bytes загруженного файла.

Если artifact отсутствует на диске:

```http
HTTP/1.1 404 Not Found
```

```json
{
  "error": "release not found"
}
```

Если релиз недоступен:

```http
HTTP/1.1 404 Not Found
```

```json
{
  "error": "resource not found"
}
```

## Project Object

```json
{
  "id": 1,
  "name": "Desktop App",
  "slug": "desktop-app",
  "description": "Primary desktop updater stream.",
  "latest_release_url": "/api/v1/projects/desktop-app/releases/latest"
}
```

Поля:

- `id` - numeric project ID.
- `name` - display name.
- `slug` - stable URL identifier.
- `description` - optional description.
- `latest_release_url` - relative URL для latest release lookup.

## Release Object

```json
{
  "id": 2,
  "version": "1.1.0",
  "build": "build-2",
  "filename": "desktop-app-1.1.0.zip",
  "checksum_sha256": "4bf5122f344554c53bde2ebb8cd2b7e3d1600ad631c385a5d7c6e64b2f7110b2",
  "size_bytes": 12345678,
  "content_type": "application/zip",
  "release_notes": "Improved desktop rollout.",
  "created_at": "2026-06-11T10:15:30Z",
  "metadata_url": "/api/v1/releases/2",
  "download_url": "/api/v1/releases/2/download"
}
```

Поля:

- `id` - numeric release ID.
- `version` - версия, введенная администратором при загрузке.
- `build` - build label или build number, если задан.
- `filename` - download filename.
- `checksum_sha256` - SHA-256 загруженного artifact.
- `size_bytes` - размер artifact в bytes.
- `content_type` - MIME type artifact.
- `release_notes` - release notes.
- `created_at` - время загрузки релиза.
- `metadata_url` - relative URL metadata endpoint.
- `download_url` - relative URL download endpoint.

## Ошибки

JSON API возвращает ошибки в формате:

```json
{
  "error": "message"
}
```

Основные статусы:

| Status | Когда |
| --- | --- |
| `400` | Некорректный `releaseID`, например не число. |
| `401` | Нет bearer token, token неверный, key выключен или истек. |
| `403` | API key валиден, но нет `can_download`. |
| `404` | Ресурс не найден, архивирован или недоступен текущему key. |
| `429` | Сработал rate limit client API. |
| `500` | Внутренняя ошибка сервера. |
| `503` | Health check: база недоступна; или API key service недоступен. |

### 401 Unauthorized

Missing header:

```http
WWW-Authenticate: Bearer realm="update-server"
```

```json
{
  "error": "missing bearer api key"
}
```

Invalid, disabled or expired key:

```json
{
  "error": "invalid api key"
}
```

### 403 Forbidden

```json
{
  "error": "api key permission denied"
}
```

### 429 Too Many Requests

```http
Retry-After: 3
```

```json
{
  "error": "rate limit exceeded"
}
```

По умолчанию client API rate limit настраивается переменными:

```text
APP_CLIENT_RATE_LIMIT_PER_MINUTE=120
APP_CLIENT_RATE_LIMIT_BURST=60
```

## Headers

Для protected API responses сервер добавляет:

```http
Cache-Control: no-store, private, max-age=0
Pragma: no-cache
Expires: 0
Vary: Authorization
X-Robots-Tag: noindex, nofollow
```

Также на все ответы добавляются security headers, включая:

```http
X-Content-Type-Options: nosniff
X-Frame-Options: DENY
Referrer-Policy: no-referrer
```

Если `APP_BASE_URL` использует `https://`, включается:

```http
Strict-Transport-Security: max-age=31536000
```

## Типовой Client Flow

1. Администратор создает проект в `/admin/projects`.
2. Администратор загружает release artifact в проекте.
3. Администратор создает API key в `/admin/api-keys`.
4. Для ключа включает `can_download`.
5. Для ключа выбирает scope, который разрешает доступ к проекту.
6. Клиент запрашивает latest release:

   ```bash
   curl -sS \
     -H "Authorization: Bearer upsk_replace_me" \
     https://updates.example.com/api/v1/projects/desktop-app/releases/latest
   ```

7. Клиент сравнивает `release.version` со своей текущей версией.
8. Если версия новая, клиент скачивает `release.download_url`.
9. Клиент проверяет:
   - `checksum_sha256`;
   - `size_bytes`;
   - при необходимости свою подпись artifact, если она есть в продукте.

## Python Example

В репозитории есть минимальный helper:

```text
example/autoupdate.py
example/update_client.py
```

Приватный файл рядом со скриптом:

```json
{
  "base_url": "https://updates.example.com",
  "api_key": "upsk_replace_me",
  "project_slug": "desktop-app"
}
```

Вызов:

```python
from autoupdate import ensure_updated_from_config

ver = "1.0.0"
ensure_updated_from_config(current_version=ver)
```

Если `autoupdate.json` отсутствует, helper создаст файл с placeholder values,
не пойдет в сеть и выведет короткое сообщение о настройке конфига.

## Чего Сейчас Нет В API

На текущий момент client JSON API не предоставляет:

- создание/редактирование проектов;
- загрузку релизов;
- создание/редактирование API keys;
- список всех релизов проекта;
- release channels вроде `stable` / `beta`;
- query parameters вроде `platform`, `arch`, `current_version`;
- публичные downloads без API key.

Эти действия либо выполняются через admin web UI, либо пока являются будущим
расширением API.