Docs

Русский

English
Türkçe

Русский

English
Türkçe

Оформление

Основы API ​

Всё, что Pano делает для посетителей, доступно по HTTP. Это краткая версия: где живёт API, как выглядит ответ, как разбиваются на страницы списки и как Pano сообщает, что что-то будет удалено.

Где он живёт ​

Каждый публичный путь начинается с /api/v1. Попробуйте на своём сайте:

sh
curl http://localhost:8088/api/v1/site-info
ЧастьПутьОбещание
API сайта (ядро)/api/v1/...Публичный. Только дополнения.
API плагина/api/plugins/<pluginId>/...Публичный. <pluginId> это полный идентификатор, например pano-plugin-market.
Сервисы ядра для плагина/api/v1/plugins/<pluginId>/_/...Публичный. _ зарезервирован за ядром.
API панели/api/v1/panel/...Внутренний. Панель и платформа выходят вместе.
Установка, узел, обслуживание/api/v1/setup, /node, /maintenanceВнутренний.

Эндпоинты панели плагина находятся по /api/plugins/<pluginId>/panel/.... Больше ничего под /api не отдаётся, а /panel/api не существует.

Пространство имён плагинов ​

  • В путях плагина нет версии: /api/plugins/<pluginId>/.... Плагин владеет своим API и версионирует его сам; обещание /api/v1 ядра его не покрывает. Старые пути /api/v1/plugins/<pluginId>/... отвечают 404.
  • panel и _ зарезервированные первые сегменты. panel отмечает эндпоинты администратора плагина, _ отмечает собственные сервисы ядра о плагине (translations, openapi.json, ui.zip), они остаются под /api/v1/plugins/<pluginId>/_/.
  • Управление плагинами остаётся в ядре по /api/v1/panel/plugins/....
  • Пять списков ядра переименованы в items: боковая панель поддержки onlineAdmins, поиск игроков в панели players, ожидающие серверы servers, игроки сервера players и ПО software. Только постраничные списки несут page.

Ответы ​

Успешный ответ это обычный JSON-объект. Обёртки result нет:

json
{ "message": "hi" }

Неуспешный ответ всегда одной формы, для любого эндпоинта:

json
{ "error": { "code": "INVALID_FIELDS", "fields": { "email": "EXISTS" } } }

code есть всегда и не меняется между релизами. message (по-английски, для тех, кто читает логи), details и fields приходят, только если есть что сказать. Проверяйте code, а не текст HTTP.

Каждый ответ несёт заголовок Pano-Api-Level: уровень API этого Pano. Он растёт, когда контракт расширений получает что-то новое.

Списки и страницы ​

Запрашивайте страницу через page (с 1) и pageSize (до 100):

sh
curl "http://localhost:8088/api/v1/posts?page=2&pageSize=20"
json
{ "items": [ ], "page": { "number": 2, "size": 20, "totalItems": 57, "totalPages": 3 } }
  • pageSize вне 1..100 отклоняется с INVALID_FIELDS и fields.pageSize = OUT_OF_RANGE. Молча он не обрезается.
  • Страница за последней отвечает 404 PAGE_NOT_FOUND. Пустой список отвечает страницей 1 и totalPages: 0.
  • Несколько внутренних списков (поиск по консоли, оповещения) используют limit и cursor и отвечают page.nextCursor.

Уровни, стабильность, устаревание ​

  • Публичные операции только растут. Ничего не удаляется и не переименовывается, поле не меняет тип и не исчезает, поле запроса не становится обязательным, код ошибки не меняется.
  • Устаревшие операции продолжают работать. В документе OpenAPI они помечены deprecated: true и отвечают заголовками Deprecation: true и Sunset: <дата>.
  • Устаревшая операция удаляется не раньше чем через 6 месяцев после релиза, объявившего её устаревшей, в дату Sunset.
  • Плагины и темы объявляют нужный им уровень API. Pano запускает ресурс, только если его уровень между минимальным и текущим уровнем сайта.

Ограничения частоты ​

Вызовы ограничиваются по адресу посетителя. Ограниченные вызовы отвечают 429 RATE_LIMIT_EXCEEDED и заголовками X-RateLimit-Limit, X-RateLimit-Remaining и Retry-After. Фронтенд, обслуживающий много посетителей, использует ключ фронтенда, чтобы получить собственные корзины.

Дальше ​

Copyright © 2026 Pano