Программный интерфейс реестра (Registry API)

Публичный программный интерфейс

Публичный интерфейс версии 0.1 доступен только для чтения:

• GET /v0.1/servers?search=&cursor=&limit= — серверы, доступные для поиска и имеющие текущую активную версию;
• GET /v0.1/servers/{name}/versions — активные неизменяемые версии;
• GET /v0.1/servers/{name}/versions/latest — явно указанная текущая версия;
• GET /v0.1/servers/{name}/versions/{version} — одна активная неизменяемая версия.

В ответах используется устойчивая постраничная выдача по курсору. Непроверенные, отклонённые, снятые с публикации и неактуальные кандидатные версии не показываются при поиске. Исторический манифест никогда не пересоздаётся по текущим изменяемым метаданным сервера.

Программный интерфейс автора

Все авторские маршруты, кроме регистрации, требуют заголовок X-API-Key: hwh_...:

• POST /api/v1/authors/register — создаёт автора и единственный раз возвращает ключ программного интерфейса;
• POST /api/v1/namespaces — создаёт DNS TXT-проверку;
• POST /api/v1/namespaces/{prefix}/verify — подтверждает DNS TXT-проверку;
• POST /api/v1/servers — создаёт первую ожидающую публикацию;
• GET /api/v1/servers/mine — показывает публикации аутентифицированного автора;
• GET /api/v1/servers/mine/{server_id} — показывает версию, адрес, состояние проверки и работоспособность;
• POST /api/v1/servers/{server_id}/releases — создаёт новую неизменяемую кандидатную версию с новым адресом;
• POST /api/v1/servers/{server_id}/withdraw — скрывает сервер из поиска, не удаляя историю версий.

Программный интерфейс администратора

Для маршрутов модерации нужен заголовок X-Admin-Key. Утверждение атомарно повышает проверенную версию до активной, устанавливает текущую версию и адрес сервера, а предыдущий адрес помечает как replaced («заменён»). Проверку адреса намеренно выполняет фоновый обработчик, где применяются ограничения SSRF и снимки возможностей.

Операторская панель управления

Тот же X-Admin-Key защищает операторские представления только для чтения. Это не публичные интерфейсы каталога: их нельзя открывать браузерам или хранить в клиентском коде.

• GET /api/v1/admin/overview — число ожидающих проверки и модерации версий, активных серверов, включённых источников и неисправных адресов;
• GET /api/v1/admin/moderation-queue?limit=50 — ограниченная очередь версий, ожидающих проверки или модерации, включая состояние адреса и число проверенных инструментов;
• GET /api/v1/admin/sources — настроенные источники синхронизации, явное состояние включения и результат последней синхронизации;
• GET /api/v1/admin/servers/{server_id}/health-history?limit=50 — ограниченная история последних проверок работоспособности выбранного сервера.

Эти представления намеренно не содержат учётных данных издателя, ключей программного интерфейса, исходных импортированных записей, тел запросов к адресу и секретов моделей. Существующие маршруты утверждения, отклонения, регистрации и включения источника остаются явными операциями изменения и требуют тот же ключ администратора.

Управление учётными записями портала также защищено X-Admin-Key:

• GET /api/v1/admin/portal-users — показывает пользователей и назначенные системные роли без хешей паролей и токенов сессий;
• POST /api/v1/admin/portal-users/{user_id}/roles — назначает одну из проверенных системных ролей (admin, moderator, employee, developer, mcp_developer, skill_developer, teacher, student, user, corporate).

Публичная регистрация может создать только роль user («пользователь»). Корпоративными организациями и их пользовательскими группами управляют через панель сотрудников. Они не могут создавать системные роли Hexwave.