Запрос по ID, параметры и срок жизни

Публичный API возвращает экспорт по ID, выданному редактором. Авторизация и API-ключ не требуются.

GET и адрес

GET https://www.block-display.com/server-api?id=123456&tag=my_model

Параметр	Обязательный	Значение
id	Да	Шестизначный ID публикации из окна экспорта
tag	Нет	Значение для подстановки в строки экспорта; по умолчанию bde

123456 во всех примерах - условный ID. Замените его действующим ID своего экспорта.

curl "https://www.block-display.com/server-api?id=123456&tag=my_model"

API также поддерживает HEAD и предварительный запрос OPTIONS. Для получения JSON используйте GET: ответ HEAD не содержит тела.

Параметр id и срок жизни

ID экспорта отличается от ID модели в каталоге и от поля content.project_id. Получайте его после успешной публикации через Export to Minecraft Server.

Экспорт доступен 10 минут с момента публикации:

• Его можно получать несколько раз, в том числе с разными tag.
• Скачивание не удаляет экспорт и не продлевает срок доступности.
• Для обновлённого проекта нужно опубликовать экспорт заново.
• После истечения срока повторная публикация выдаст новый ID.

ID предназначен для получения опубликованных данных. Для длительного использования сохраняйте сам полученный экспорт. Правила его хранения определяет ваша интеграция.

Необязательный tag

API подставляет значение tag вместо [BDESERVERTAG] в строках экспорта. Например, при tag=my_model:

[BDESERVERTAG]_root → my_model_root
[BDESERVERTAG]_0    → my_model_0

Правила обработки:

Правило	Поведение
Допустимые символы	Латинские буквы, цифры, _ и -
Регистр	Сохраняется
Другие символы	Удаляются
Максимальная длина	100 символов
Отсутствующее или пустое значение	Используется bde

Подстановка применяется к строкам данных, а не только к массивам Tags: маркер может встречаться в селекторах и командах. Она не изменяет сохранённый экспорт. Один ID можно получить с разными tag и получить разные варианты строк.

tag не создаёт экземпляр модели и не управляет его жизненным циклом. Смысл тегов частей: passengers: визуальные части.

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

Успешный GET возвращает HTTP 200 и JSON с объектом content. Типы полей и учебные примеры приведены в статье Структура JSON. Наличие анимаций, звука и других дополнительных данных зависит от экспорта.

Быстрая команда в редакторе

Вместе с ID редактор показывает готовую команду. По умолчанию это /bde spawn {ID} с подставленным ID публикации. Через «Изменить быструю команду» можно заменить префикс bde spawn своим значением.

Это настройка текста для копирования. Команду в Minecraft обрабатывает серверный плагин пользователя; HTTP API от изменения команды не меняется. Подробнее о настройке в редакторе.

Ограничения запросов

На один внешний IP-адрес одновременно действуют два ограничения:

Лимит	Период
120 запросов	60 секунд
1200 запросов	3600 секунд

Каждое окно начинается с первого запроса после сброса соответствующего счётчика. Исчерпания любого из двух лимитов достаточно для ответа 429.

Разные ID и значения tag используют общую квоту. Запросы с неверным ID тоже учитываются. Клиенты за NAT или другим общим внешним IP делят один лимит. GET и HEAD расходуют квоту, OPTIONS не расходует.

При 429 заголовок Retry-After содержит ожидание в секундах. То же значение возвращается в error.retryAfterSeconds.

Retry-After: 45

45 - пример, а не постоянная задержка. Используйте значение из конкретного ответа.

Заголовок	Назначение
X-RateLimit-Limit	Лимит, описываемый заголовками ответа
X-RateLimit-Remaining	Оставшееся количество запросов для этого ограничения
X-RateLimit-Reset	Оставшиеся секунды до сброса соответствующего ограничения

X-RateLimit-Reset содержит длительность ожидания, не Unix timestamp. Один набор заголовков не отменяет второе ограничение; при 429 ориентируйтесь на Retry-After.

Запросы из браузера

Публичный API разрешает обращения с любого сайта:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, HEAD, OPTIONS
Access-Control-Allow-Headers: *

Предварительный OPTIONS возвращает 204. Передача cookies не требуется и режим credentials: "include" не поддерживается. Для браузерного запроса используйте credentials: "omit".

const url = new URL('https://www.block-display.com/server-api');
url.searchParams.set('id', '123456'); // Замените на ID своего экспорта.
url.searchParams.set('tag', 'my_model');

const response = await fetch(url, { credentials: 'omit' });
console.log(response.status, await response.text());

Пример получает и показывает ответ, включая текст ошибки. Он не создаёт модель в Minecraft. Браузерному JavaScript доступны заголовки Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.

Неуспешный ответ

Проверяйте HTTP-статус до использования content. Ошибка может содержать error в виде строки или объекта; при инфраструктурном сбое тело может быть пустым или не быть JSON. Все предусмотренные статусы и примеры: Ошибки, версии и совместимость.