AllStore API v3 — полная документация

Этот раздел описывает все HTTP-точки входа API, присутствующие в текущем сервере AllStore. Для новых клиентов используйте /api/v3; совместимые публичные адреса /api/apps и некоторые служебные /api/* сохранены для старых клиентов.

Базовый адрес: http://alldevicestore.ru
Основной префикс: http://alldevicestore.ru/api/v3
Кодировка: UTF-8. Метаданные: JSON или form-data. Файлы: multipart/form-data.
Машиночитаемый список маршрутов: http://alldevicestore.ru/api/v3.

1. Формат ответа и авторизация

Большинство v3-методов используют единый контейнер ответа:

{"status":"ok","api_version":3,"data":{...}} {"status":"error","api_version":3, "error":{"code":"invalid_token","message":"Нужен действующий Bearer-токен."}}

Списковые методы дополнительно могут возвращать pagination, а некоторые — filters, summary или другие служебные поля верхнего уровня. Клиенту рекомендуется игнорировать неизвестные поля для прямой совместимости с будущими обновлениями.

Авторизованные запросы передают токен в заголовке:

Authorization: Bearer ВАШ_ТОКЕН Accept: application/json

Токен создаётся при регистрации или входе, действует 90 дней и повторно в открытом виде не выдаётся. После смены пароля остальные API-токены и старые веб-сеансы отзываются. При обязательной смене пароля разрешены только GET /api/v3/me, PUT /api/v3/me/password и POST /api/v3/auth/logout.

Роли: user, developer, moderator, admin, creator. Обозначение Staff ниже означает moderator/admin/creator.

2. Быстрый старт — Python

import json
from urllib.request import Request, urlopen

BASE = "http://alldevicestore.ru" # Вход body = json.dumps({ "username": "login", "password": "password", "client_name": "My Python client" }).encode("utf-8") req = Request(BASE + "/api/v3/auth/login", data=body, headers={"Content-Type": "application/json"}, method="POST") with urlopen(req) as r: token = json.load(r)["data"]["token"] # Авторизованный запрос req = Request(BASE + "/api/v3/me", headers={"Authorization": "Bearer " + token, "Accept": "application/json"}) with urlopen(req) as r: profile = json.load(r)["data"] print(profile["username"])

3. Быстрый старт — Java ME / Java

Пример рассчитан на MIDP/CLDC HttpConnection. На обычной Java логика та же, но можно использовать стандартный HTTP-клиент своей версии JDK.

HttpConnection c = (HttpConnection) Connector.open(baseUrl + "/api/v3/me");
c.setRequestMethod(HttpConnection.GET);
c.setRequestProperty("Accept", "application/json");
c.setRequestProperty("Authorization", "Bearer " + token);

int code = c.getResponseCode();
InputStream in = c.openInputStream();
ByteArrayOutputStream out = new ByteArrayOutputStream();
byte[] buf = new byte[1024];
int n;
while ((n = in.read(buf)) != -1) out.write(buf, 0, n);
String json = new String(out.toByteArray(), "UTF-8");
in.close();
c.close();

Для Java ME используйте небольшой per_page (например 10), читайте ответы потоково и не запрашивайте gzip, если устройство само его не распаковывает. Bearer-токен передавайте только по HTTPS и храните как секрет, например в RMS.

4. Все точки входа API

* Наличие Bearer-токена или подходящей роли не гарантирует право на конкретный объект: сервер дополнительно проверяет автора материала, иерархию ролей, состояние объекта, revision и другие ограничения.

5. Регистрация, вход и токены

POST /api/v3/auth/register

JSON/form-data: username (3–32 символа: буквы, цифры, _, -), password (8–256), необязательно client_name. Создаёт обычного пользователя и сразу возвращает user, token, token_type=Bearer, expires_at. HTTP 201.

POST /api/v3/auth/login

Поля: username, password, необязательно client_name. После серии ошибочных попыток действует ограничение входа; возможен HTTP 429.

POST /api/v3/auth/login
Content-Type: application/json

{"username":"demo","password":"StrongPassword123","client_name":"AllStore J2ME"}

POST /api/v3/auth/logout

Отзывает только токен, которым выполнен текущий запрос.

GET /api/v3/me/tokens

Возвращает активные токены с метаданными и признаком current, но никогда не возвращает их секретное значение.

DELETE /api/v3/me/tokens/{token_id}

Отзывает токен текущего пользователя по его ID.

6. Профиль и пользовательские настройки

GET /api/v3/me

Приватный профиль: публичные поля плюс email, website, country, birth_date, must_change_password и settings.

PATCH /api/v3/me

Изменяемые поля: username, description, email, website, country, birth_date. Иконку можно передать multipart-полем icon. Новые строки в описаниях сохраняются; в JSON используйте \n.

DELETE /api/v3/me

Удаляет собственный аккаунт. Аккаунт с ролью creator защищён от этого метода.

PUT /api/v3/me/password

JSON: old_password, new_password. Новый пароль не должен совпадать с текущим или использованными за последние 30 дней. При успехе сервер отзывает остальные токены и старые веб-сеансы.

GET /api/v3/users/{username}

Публичный профиль пользователя и массив его опубликованных приложений.

GET/PATCH /api/v3/me/settings

Настройки интерфейса. Текущий сервер поддерживает поля theme, text_size, density, ico_mode и связанные поддерживаемые сервером настройки. PATCH изменяет только переданные допустимые поля.

GET /api/v3/me/warnings

Список собственных предупреждений с пагинацией.

7. Каталог приложений

GET /api/v3/apps

Query-параметры: page, per_page (1–100), q, category, device, device_category, sort = popular|new|rating, search_versions=0|1. По умолчанию поиск учитывает коллекции версий.

GET http://alldevicestore.ru/api/v3/apps?q=opera&device_category=Java%20ME&sort=new&per_page=10

Краткая карточка содержит, среди прочего: id, name, package_name, version, платформу, описания, число загрузок, рейтинг, автора, URL и размер основного файла, и version_collection.

GET /api/v3/apps/{app_id}

Добавляет полное описание, keywords, скриншоты, дополнительные файлы, последние комментарии, профиль автора и статус.

Совместимые GET /api/apps и /api/apps/{app_id}

Сохраняются для старых клиентов. В старом списке per_page ограничен 50; структура пагинации исторически отличается от v3. Для нового клиента используйте v3.

8. Публикация и редактирование приложения

POST /api/v3/apps принимает метаданные и файлы. Удобнее всего использовать multipart/form-data.

Основные поля: name, package_name, version, category, device_version_id, short_description, description. Ключевые слова сервер может сформировать автоматически. Файлы: icon, app_file, повторяемые screenshots, повторяемые extra_files. Лимит основного файла зависит от выбранной версии устройства из /api/devices.

curl -X POST "http://alldevicestore.ru/api/v3/apps" \ -H "Authorization: Bearer TOKEN" \ -F "name=My App" \ -F "package_name=com.example.app" \ -F "version=1.0" \ -F "category=Утилиты" \ -F "device_version_id=2" \ -F "short_description=Кратко" \ -F "description=Полное описание" \ -F "app_file=@application.jar" \ -F "icon=@icon.png"

PATCH /api/v3/apps/{app_id} использует те же поля. Новые скриншоты и extra_files добавляются к существующим. DELETE скрывает материал, а не обязательно физически удаляет файлы; можно передать reason. POST .../restore восстанавливает материал, если текущему пользователю это разрешено.

9. ZIP-импорт

POST /api/v3/apps/import

Multipart: от 1 до 10 полей archives, каждое содержит ZIP. Ответ — массив результатов по архивам. Полный успех: HTTP 201; частичный: HTTP 207.

POST /api/v3/apps/{app_id}/import

Multipart: один archives. Используется для обновления существующего приложения; сервер проверяет связь пакета и права на приложение. При ZIP-обновлении ожидаются метаданные формата AllStore (app.json/update.json согласно странице формата ZIP).

Открыть документацию формата ZIP.

10. Коллекции версий, build, языки и файлы

GET /api/v3/apps/{app_id}/versions

Query: page, per_page (1–100), q, language, version, build, variant, device, midp, cldc, sort.

Сортировки: newest, oldest, version_asc, version_desc, build_asc, build_desc, size_desc.

GET /api/v3/apps/{app_id}/versions/{version_id}

Возвращает полную запись версии, метаданные, предупреждения, список языков и файлы.

GET /api/v3/apps/{app_id}/versions/{version_id}/files

Возвращает языковые варианты и их файлы. У файла доступны метаданные, оригинальное имя, размер, MIME, SHA-256 и download_url.

Три адреса также имеют публичные алиасы без /v3: /api/apps/....

GET /api/languages

Возвращает установленные языковые пакеты интерфейса, fallback-язык и выбранный язык текущего контекста.

11. Комментарии и рейтинг

GET /api/v3/apps/{app_id}/comments

Публичный список с пагинацией. Параметр parent_id: значение ID — ответы указанного комментария; пустой parent_id= — только корневые комментарии. Ответы содержат автора и данные для отображения цепочки.

POST /api/v3/apps/{app_id}/comments

JSON: text и необязательно parent_id. Сервер проверяет приложение, родительский комментарий и допустимую глубину ответов.

PATCH /api/v3/comments/{comment_id}

JSON: text, 1–4000 символов. Редактировать можно свой опубликованный комментарий.

DELETE /api/v3/comments/{comment_id}

Необязательно reason. Фактическое право зависит от автора и роли.

POST /api/v3/comments/{comment_id}/restore

Необязательно reason. Нельзя восстановить комментарий раньше скрытого родительского приложения.

PUT /api/v3/apps/{app_id}/rating

JSON: {"score":5}. Оценка — целое число 1–5. Повторный PUT меняет собственную оценку.

DELETE /api/v3/apps/{app_id}/rating

Удаляет собственную оценку.

12. Избранное и собственные приложения

GET /api/v3/me/favorites — пагинированный список избранного.

PUT /api/v3/me/favorites/{app_id} — добавить; DELETE — удалить.

GET /api/v3/me/apps — приложения текущего автора, включая скрытые; ответ дополнительно содержит status и removal_reason.

13. Личное JSON-хранилище внешнего клиента

Эти маршруты предназначены для настроек/прогресса сторонних клиентов, которые нужно синхронизировать с аккаунтом AllStore.

GET /api/v3/me/client-data — список namespace и лимит. Namespace: 1–64 символа A-Z a-z 0-9 _ . -.

GET /api/v3/me/client-data/{namespace} — получить значение; отсутствующий namespace возвращает пустой объект.

PUT /api/v3/me/client-data/{namespace} — сохранить JSON. Можно передать {"value": ...}; если ключа value нет, сохраняется всё тело. Максимум 64 КБ UTF-8 на namespace.

DELETE /api/v3/me/client-data/{namespace} — удалить.

PUT /api/v3/me/client-data/my.javame.client
Authorization: Bearer TOKEN
Content-Type: application/json

{"value":{"last_page":3,"compact":true}}

14. Личные CSS-стили

GET /api/v3/me/styles — список собственных CSS и active_style_id.

POST /api/v3/me/styles — multipart-поле css_file; валидный стиль сохраняется и становится активным.

PUT /api/v3/me/styles/{style_id} — выбрать стиль. Значение ID 0 используется сервером для отключения личного стиля.

DELETE /api/v3/me/styles/{style_id} — удалить собственный стиль.

15. Жалобы

POST /api/v3/reports

JSON: type = user|app|comment, target_id, reason. Сервер проверяет цель и ограничения повторных/самостоятельных жалоб.

GET /api/v3/reports

Обычный пользователь видит свои обращения, Staff — доступную очередь. Поддерживаются page, per_page, status, type, priority, q, mine=1; для сотрудников также assignment=mine|unassigned.

GET /api/v3/reports/{report_id}

Возвращает data.report и data.events. Для обычного пользователя служебные поля/внутренние события скрываются.

PATCH /api/v3/reports/{report_id}

Workflow использует action: claim, assign, priority, note, resolve, reject, reopen, withdraw. Для конкурентного редактирования передавайте актуальное revision; устаревшая revision даёт HTTP 409. Для назначения применяется assignee_id, для приоритета — priority, для текстовых действий — reason. При resolve сервер также поддерживает санкции, предусмотренные текущим workflow.

POST /api/v3/reports/{report_id}/resolve

Совместимый сокращённый вариант resolve для Staff; тело может содержать параметры решения и reason.

POST /api/v3/reports/bulk

Массовая Staff-операция. Формат строится на том же механизме действий и revision, что и единичная модерация.

16. Управление пользователями и журнал

GET /api/v3/admin/users

Staff-список с пагинацией и фильтрами. Поддерживаются поиск q, фильтры роли/статуса и сортировка, реализованные текущим сервером. Admin/creator получают дополнительные приватные поля; чувствительные секреты не выдаются.

PATCH /api/v3/admin/users/{user_id}

Поля role и/или banned, необязательно reason, рекомендуется revision. Смена роли ограничена иерархией полномочий.

POST /api/v3/admin/users/{user_id}/actions

action: warn, note, ban, unban, role, revoke_sessions, reset_password. Передавайте reason; для ban — duration_hours; для role — role; для защиты от гонок — revision. Сброс пароля может вернуть одноразово сгенерированный temporary_password.

GET /api/v3/admin/users/{user_id}/history

Пагинированная история аудита выбранного пользователя, если сотруднику разрешено управлять целью.

POST /api/v3/admin/users/bulk

Массовые действия для Staff с проверкой полномочий отдельно для каждой цели.

GET /api/v3/admin/logs?limit=200

Только creator. limit = 1–1000. Возвращает разобранные последние строки server log.

17. Справочники и диагностика

GET /api/categories — список категорий.

GET /api/devices — иерархия категорий/версий устройств и их ограничения. Используйте ID версии устройства при публикации приложения.

GET /api/languages — языковые пакеты интерфейса.

GET /api/client-info — компактный feature discovery для клиентов.

GET /api/health — service, site_version, состояние SQLite и UTC-время. При проблеме БД возвращает HTTP 503.

GET /api/upload-progress/{job_id} — исторический маршрут прогресса фоновой загрузки из веб-интерфейса. Он сверяет владельца через обычную Flask-сессию и не принимает Bearer как замену сеанса.

18. Пагинация, даты, текст и HTTP-коды

Стандартная пагинация v3:

"pagination": {
  "page": 1,
  "per_page": 25,
  "total_items": 123,
  "total_pages": 5
}

Даты серверных операций передаются как ISO 8601 UTC. Многострочный пользовательский текст хранится как обычный текст: в JSON новая строка записывается как \n; HTML пользователя не исполняется.

19. Рекомендации клиенту

• Для новых приложений фиксируйте major-версию URL: /api/v3.
• Всегда обрабатывайте HTTP-код до разбора data; при ошибке читайте error.code и error.message.
• Не сохраняйте пароль пользователя. После входа храните только Bearer-токен и удаляйте его при logout.
• Не передавайте Bearer по незашифрованному HTTP.
• Не предполагайте, что ID числовые: большинство ID AllStore — строки.
• Не собирайте URL скачивания вручную — используйте download_url, icon_url, screenshot_urls и URL файлов версии из ответа сервера.
• Для слабых устройств уменьшайте per_page, освобождайте поток/соединение сразу после чтения и парсите JSON без создания лишних копий строки.

Открыть свой сервер API

API управления публичными серверами доступен только роли creator.

Создание и замена server.py используют multipart/form-data с полем server_file.

Действие action принимает start, stop, restart, reallocate_port или clear_log.

PATCH принимает name, description, enabled, autostart, restart_policy, restart_delay, restart_limit, memory_limit_mb, max_processes, max_open_files, max_file_size_mb, storage_limit_mb, max_files, nice_level, request_limit_mb/request_limit_bytes, proxy_timeout и max_concurrent_requests.

Ответ содержит runtime со state, running, pid, port_open, listener_scope и healthy.

Публичный путь проксирует HTTP через AllStore; WebSocket и raw TCP/UDP не поддерживаются этим URL-маршрутом.

Authorization: Bearer <creator-token>
Content-Type: application/json

{"action":"restart"}

Совместимость с устройствами — AllStore 3.7

API совместимости использует /api/v3/devices и /api/v3/apps/{id}/compatibility.

Оценка намеренно консервативна: отсутствие данных по обязательному требованию даёт possible, а не ложное supported. Ручной override имеет приоритет. Старые поля device, device_category и device_version_id сохранены.