REST API приложения и документация API

Q: Почему я не могу опубликовать конечную точку?

Для операций Создать, Обновить или Удалить сначала включите это действие для таблицы в разделе «Админ». Приложение, рабочая база которого находится в вашем собственном аккаунте Cloudflare, не может публиковать конечные точки из MonstarX, потому что здесь хранятся тренировочные данные предпросмотра.

КраткоНа вкладке «Админ» раздел «API» превращает таблицы приложения в конечные точки REST, к которым могут обращаться другие программы: получать список записей или одну запись, создавать, обновлять и удалять записи. Вы выбираете таблицу, поля и кто может обращаться (кто угодно — для чтения или только с ключом API проекта), а затем включаете точку галочкой «Опубликовать конечную точку». Когда захотите поделиться, нажмите «Опубликовать документацию» — появится страница справочника API и файл OpenAPI для разработчиков.

Иногда данные приложения нужны другим программам: сайту партнёра, который показывает ваши товары, таблице, которая подтягивает новые заказы, мобильному приложению, сервису автоматизации вроде Zapier или n8n. Они общаются с приложением через API — набор веб-адресов (конечных точек), которые отвечают данными, а не страницами. REST API — самый распространённый вид API.

MonstarX создаёт его без кода. Вы выбираете, чем поделиться, — и через несколько секунд API уже работает, а у разработчиков есть страница справочника.

Где его найти?

Откройте проект, нажмите Админ на верхней панели, а затем API на боковой панели раздела «Админ». Откроется страница API проекта: вверху — панель Справочник API, через которую публикуется документация; слева — ваши конечные точки с пометкой Работает или Черновик; под ними — Ключи API.

Раздел «API» на вкладке «Админ» у приложения «Домашняя кухня»: панель «Справочник API» с пометкой «Опубликовано» и «Работающие конечные точки: 1», открыта работающая конечная точка GET /recipes «Список Рецепты» — название, путь, коллекция и операция

Как создать конечную точку?

В разделе АдминAPI нажмите Новая конечная точка (или + рядом с Конечные точки).
В поле Коллекция выберите таблицу, с которой работает конечная точка, например Рецепты.

В поле Операция выберите действие:

Операция	Метод и адрес	Что делает
Список	`GET /recipes`	Возвращает записи постранично.
Получить	`GET /recipes/{id}`	Возвращает одну запись по её id.
Создать	`POST /recipes`	Добавляет запись.
Обновить	`PATCH /recipes/{id}`	Меняет некоторые поля записи.
Удалить	`DELETE /recipes/{id}`	Удаляет запись.

Заполните Название, Путь URL и, если хотите, Описание. Они появятся в документации API.
В блоке Открытые поля отметьте ровно те поля, которые можно видеть или отправлять. Всё неотмеченное остаётся закрытым. Поля, похожие на конфиденциальные, — например, пароли и токены — исключаются всегда.
В блоке Доступ выберите, кто может обращаться к точке (см. ниже).
Отметьте Опубликовать конечную точку и нажмите Сохранить и опубликовать конечную точку. Опубликованная точка получает пометку Работает: она сразу отвечает на запросы. Если оставить галочку пустой, кнопка Сохранить конечную точку сохранит её с пометкой Черновик.

В списке у каждой конечной точки написано Работает или Черновик. Та же пометка видна под заголовком Изменить конечную точку, а пока вы не сохраните изменения, рядом будет Несохранённые изменения. Чтобы отключить точку, не удаляя её, снимите галочку Опубликовать конечную точку и сохраните; кнопка Удалить удаляет точку.

Кто может обращаться к конечным точкам?

Доступ	Кто может обращаться	Для каких операций
Публичное чтение	Любой, у кого есть адрес.	Только Список и Получить
Ключ API проекта	Только те, кто передаёт один из ключей API вашего проекта.	Для всех операций

Конечным точкам, которые меняют данные, ключ нужен всегда.

Как создать ключ API?

В разделе АдминAPI нажмите Ключи API.
Введите название, по которому будет понятно, где используется ключ, например «Сервер виджета рецептов», и нажмите Создать ключ.
Сразу скопируйте ключ — он начинается с mxapi_, и показать его ещё раз нельзя. Сохраните его в надёжном месте, например в менеджере паролей или в секретах другого сервиса.

«Ключи API проекта»: введено название ключа, кнопка «Создать ключ» и пометка, что ключи дают доступ ко всем защищённым ключом конечным точкам и каждый ключ показывается только один раз

Один ключ открывает все защищённые ключом конечные точки проекта, поэтому выдавайте каждому сервису свой ключ. Чтобы отключить ключ, нажмите Отозвать — всё, что им пользовалось, сразу перестанет работать.

Ключ передаётся в заголовке Authorization: Authorization: Bearer mxapi_….

Как проверить конечную точку?

Откройте конечную точку и нажмите Тест. Заполните ID записи, Bearer-токен или Тело запроса JSON, если они нужны этой точке, и нажмите Отправить запрос. Вы увидите статус (200 означает, что всё сработало), время ответа и сам ответ. Для точки, которой нужен ключ, вставьте в поле Bearer-токен один из ключей из раздела Ключи API.

Тесты уходят на настоящую работающую конечную точку, поэтому:

Черновик пока нельзя проверить. На вкладке Тест будет написано Эта конечная точка — черновик; нажмите там Сохранить и опубликовать конечную точку, чтобы опубликовать и проверить её.
Сначала сохраните изменения. Если есть несохранённые изменения, вкладка Тест попросит сохранить их перед проверкой и покажет кнопку Сохранить конечную точку.

Вкладка «Тест» для GET /recipes: полный адрес на monstarx.com, кнопка «Отправить запрос» и ответ 200 со списком рецептов в JSON

Тест операций Создать, Обновить или Удалить меняет ваши настоящие данные.

На вкладке Код есть готовая команда cURL для копирования и файл OpenAPI JSON, который можно импортировать в инструменты для API вроде Postman и Insomnia.

Вкладка «Код»: команда cURL для GET /recipes с кнопкой «Копировать» и ссылка на файл OpenAPI JSON

Как опубликовать документацию API и поделиться ею?

Документация API — это страница Справочник API для разработчиков: все работающие конечные точки, их поля, нужен ли ключ, поле Проверить и пример cURL. Публикация конечной точки не публикует документацию — когда ею делиться, решаете вы.

Опубликуйте хотя бы одну конечную точку и сохраните все изменения. До этого панель Справочник API вверху раздела АдминAPI показывает Не опубликовано и подсказывает, чего не хватает.
Нажмите Опубликовать документацию.
Теперь на панели написано Опубликовано. Нажмите Копировать ссылку на документацию, чтобы поделиться адресом, или Открыть документацию API под блоком Ключи API, чтобы посмотреть страницу. Адрес выглядит так: https://monstarx.com/api-docs/<id вашего проекта>.

Опубликованный справочник API приложения «Домашняя кухня»: название и описание проекта, «Конечные точки: 1», ID проекта и базовый адрес, а также GET /recipes с публичным чтением, открытыми полями и полем «Проверить», которое вернуло рецепты в JSON

Страница начинается с названия и описания проекта, числа конечных точек, ID проекта и базового адреса. Прочитать её может любой, у кого есть ссылка, а поисковым системам рекомендовано её не индексировать. На ней показываются только работающие конечные точки и никогда — ключи. Ссылка OpenAPI JSON вверху ведёт к тому же описанию в виде файла.

Чтобы убрать документацию, нажмите Снять документацию с публикации: страница и файл OpenAPI перестанут открываться, а конечные точки продолжат отвечать. Если вы отключите все конечные точки, документация тоже будет снята с публикации, и вы опубликуете её снова, когда будете готовы.

Как выглядят запросы и ответы?

Каждая конечная точка находится по адресу https://monstarx.com/api/rest/<id вашего проекта>, за которым следует её путь.

curl 'https://monstarx.com/api/rest/<project id>/recipes?page=1&limit=25'

{
  "data": [
    { "id": "41a6…", "title": "Street tacos al pastor", "country_code": "MX" }
  ],
  "page": 1,
  "limit": 25,
  "hasMore": false
}

limit — от 1 до 100 записей на странице (25, если не указывать), а page — от 1 до 100. hasMore показывает, есть ли следующая страница.

curl -X POST 'https://monstarx.com/api/rest/<project id>/recipes' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Lemon ricotta pancakes", "country_code": "IT"}'

В ответе (статус 201) новая запись лежит в data вместе со своим id.

curl -X PATCH 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"title": "Fluffy lemon ricotta pancakes"}'

curl -X DELETE 'https://monstarx.com/api/rest/<project id>/recipes/RECORD_ID' \
  -H 'Authorization: Bearer YOUR_PROJECT_KEY'

Обновить возвращает изменённую запись, Удалить — { "deleted": true }.

Правила для того, что вы отправляете:

объект JSON с заголовком Content-Type: application/json, до 64 КБ;
только открытые поля, каждое — простое значение: текст (до 20 000 символов), число, true/false или null;
id нельзя задать или изменить, как и поля, которые в разделе «Админ» доступны только для чтения.

Если что-то не так, в ответе будет сообщение error и статус: 400 (запрос составлен неправильно), 401 (нужен действительный ключ API проекта), 403 (эта таблица или действие не разрешены в разделе «Админ»), 404 (нет такой конечной точки или записи), 409 (конфликт, например дубликат), 413 (ответ превысил бы 1 МБ — откройте меньше полей или уменьшите страницу).

Вопросы и ответы

Почему не нажимается «Опубликовать документацию»?

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

Нужно ли публиковать приложение, чтобы API заработал?

Нет. API читает и записывает базу данных проекта напрямую, поэтому работает сразу после публикации конечной точки. Он пользуется теми же данными, что предпросмотр и рабочее приложение, и не требует ни сборки, ни ИИ, ни кредитов.

Может ли сайт обращаться к моему API из браузера?

Да, к вашим конечным точкам может обращаться любой сайт. С веб-страниц вызывайте точки с доступом Публичное чтение, а запросы с ключом держите на сервере, чтобы ключ оставался секретным.

Я потерял ключ API. Можно увидеть его снова?

Нет, ключ показывается только один раз. Создайте новый ключ, переключите на него сервис, а затем отзовите старый кнопкой Отозвать.

Почему я не могу опубликовать конечную точку?

Для операций Создать, Обновить или Удалить сначала включите это действие для таблицы в разделе «Админ». Приложение, рабочая база которого находится в вашем собственном аккаунте Cloudflare, не может публиковать конечные точки из MonstarX, потому что здесь хранятся тренировочные данные предпросмотра.

Можно ли получать вебхуки при изменении данных?

Не через «Админ → API» — этот раздел только отвечает на запросы. Попросите MonstarX добавить вебхук в приложение, например: «когда оформляется заказ, отправляй его POST-запросом на этот адрес».