Запросы

Параметры списка и карточки для зарегистрированных объектов.

Pagination

Параметр	По умолчанию	Примечание
limit	20	Не больше mxheadless_max_limit (100)
offset	0	Не больше mxheadless_max_offset
page	-	Вместо offset. Вместе с offset даёт 422

В meta: total, count, limit, offset, has_more. В links: self, next, prev при наличии.

Fields

fields=id,pagetitle,uri

Не больше mxheadless_max_fields (50) полей. Неизвестное или запрещённое поле даёт 422.

Filter

filter[published]=1
filter[parent]=5
filter[alias][like]=%news%

filter[field]=value равен filter[field][eq]=value. Синоним параметра: filters. Неизвестное поле или оператор даёт 422.

Для boolean-полей (published, deleted, hidemenu, isfolder, richtext, searchable, cacheable, uri_override, hide_children_in_tree, show_in_tree) значение нормализуется: принимаются 1, 0, true, false, yes, no, on, off и пустая строка. Остальное даёт 422.

Оператор	Синоним
eq
neq	ne
gt gte lt lte
like
in not_in
null not_null

У resources нет pagetitle в filterable. Поиск по заголовку: ?q=.

Sort

sort=menuindex
sort=-createdon
sort=menuindex,-id
sort=publishedon:desc

Префикс - или суффикс :desc задаёт DESC. :asc и + задают ASC. У resources нельзя sort=parent.

Без sort выборка сортируется по primary key объекта по возрастанию. Для resources это id, для contexts — key. Это гарантирует стабильный порядок при пагинации с offset: строки не «прыгают» между страницами. Поле, которое нужно сортировать по порядку дерева, обязано попадать в sortable.

Поиск

?q=installation

QueryParser строит LIKE %term% по полям searchable из определения. У resources в ядре: pagetitle, longtitle, description, introtext, alias, uri. Поля объединяются через OR.

Короткий термин может вернуть много строк. Сужайте выборку через filter. Если searchable пуст, ответ 422 Search not supported. Список полей: Schema.

q конфликтует с friendly URL

Значение q, совпадающее с путём запроса, вырезается из query до разбора (Psr7RequestFactory::stripRoutingQueryParams). Например, GET /api/v1/resources?q=resources обработает q как путь и поиск не выполнит. Это сделано, чтобы friendly URL MODX вида /?q=installation не конфликтовал с поиском.

Подставляйте термин так, чтобы он не был равен пути: используйте URL-кодирование, другой регистр не поможет. На части хостингов параметр может быть съеден и до входа в PHP, тогда поиск не отработает без ошибки. Проверяйте выдачу.

Includes

include=parent,children
include=tvs

У resources связи: parent, children. Поле template — id шаблона, не include. TV: include=tvs / include=tv, ?tv_fields=name1,name2 или ?include_tv=1. Чанки, шаблоны, сниппеты, TV: include=category. Категории: include=parent.

Лимиты: mxheadless_max_include_relations (10), mxheadless_max_include_depth (2). Имена связей берутся из schema.

Контекст

?context=web
X-Context: web

Заголовок удобнее для кэша. Без параметра берётся контекст запуска: mxheadless_context, по умолчанию web.

Список mxheadless_allowed_contexts (по умолчанию web,mgr) ограничивает допустимые значения. Каталог и settings: Elements и Contexts.

Preview / deleted

?preview=true
?include_deleted=1
?includeDeleted=1

Только с соответствующими правами. Подробнее: Preview, Авторизация.