Карты роутов
Карта роутов - массив описывающий правила обработки для входящего запроса.
По умолчанию, карты роутов располагаются в папке модуля /bitrix/modules/artamonov.rest/routes/.
Начиная с версии 2.7.0 в настройках модуля можно указать собственный путь к картам роутов.
Для добавления карты нужно создать PHP-файл, возвращающий массив, описывающий необходимые роуты. В качестве примера, можно ознакомиться с картой нативных роутов, расположенной по пути /bitrix/modules/artamonov.rest/routes/_native.php.
Количество карт роутов не ограничено.
<?php
/**
* Copyright (c) 2019 Denis Artamonov
* Created: 1/13/19 4:57 PM
* Author: Denis Artamonov
*
* Пример карты роутов
*/
/*
|--------------------------------------------------------------------------
| Пример карты роутов
|--------------------------------------------------------------------------
|
| Внимание!
|
| - Данный файл может быть перезаписан при обновлении модуля.
| - Данный файл исключен из публичной документации.
|
| Для добавления своих роутов, создайте собственную карту.
| Например:
| /routes/sale.php
| /routes/iblock.php
| /local/api/routes/iblock.php
| И так далее, количество карт неограниченно.
|
| Карты могут располагаться вне папки модуля. Для этого необходимо указать путь к собственной папке в настройках.
| Карты будут подгружены автоматически.
|
| Совет: не желательно разбивать карту на множество файлов,
| так как, чем больше файлов, тем больше будет происходить их подключений,
| соответственно, затрачивается дополнительное время при запуске интерфейса.
|
| А также, не забудьте указать контроллеры для обработки роутов.
| Контроллеры могут располагаться где угодно, главное чтобы они были доступны через пространство имён.
| Вместо класса можно указать любой php-файл, который будет подключен и отработан при запросе.
|
| Для получения карты из контроллера можно воспользоваться методом request()->map()
|
| Поддерживаемые типы параметров: string, integer, float, email, ip, domain, url
|
*/
return [
// Тип запроса
'GET' => [
// Роут
// Для получения всех параметров request()->get()
// Для получения конкретного параметра request()->get({parameter_name})
'example/check' => [
// Описание роута
// 'description' => 'GET',
// Активность роутра
// Необязательный параметр (по умолчанию роут активен)
//'active' => false,
// Контроллер обрабатывающий роут
// Данный ключ исключен из публичной документации
// Контроллер может располагаться за пределами модуля, главное чтобы он был доступен через пространство имён
// Где Example - класс, _get - метод класса
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_get',
// Вместо класса можно указать любой php-файл, который будет подключен и отработан при запросе
// 'controller' => $_SERVER['DOCUMENT_ROOT'] . '/local/rest/controllers/file.php',
// Безопасность участвует при запуске интерфейса
'security' => [
// Настройки авторизации при запросе
'auth' => [
// Обязательная авторизация для роута
// Происходит проверка на наличие заголовков
// 'required' => true, // true || false
// Тип авторизации используемый для роута
// Если login, тогда должны быть переданы заголовки Authorization-Login и Authorization-Password
// Если token, тогда должен быть передан заголовок Authorization-Token
// 'type' => 'login', // login || token
],
// Настройки безопасности для логинов
// Данный ключ исключен из публичной документации
'login' => [
// Доступ к методу будет доступен только для логинов из списка
'whitelist' => [
// 'admin',
]
],
// Настройки безопасности для токенов
// Данный ключ исключен из публичной документации
'token' => [
// Проверять срок годности токена
// Если токен находится в белом списке, тогда параметр игнорируется
'checkExpire' => false, // true || false
// Доступ к методу будет доступен только для токенов из списка
'whitelist' => [
// 'b3bfb6b8-82dca90f-6049641b-76d957d6',
// 'bc95d11b-f2fdf7f4-15e869d3-882e72b5',
// '408f4f2e-d5a6e4a7-06930a16-8301b343',
]
],
// Настройки безопасности для групп
// Данный ключ исключен из публичной документации
'group' => [
// Доступ к методу будет доступен только для групп из списка
// Указывается ID группы
// Если имеется белый список логинов или токенов, тогда параметр игнорируется
'whitelist' => [
// 1,
// 6,
// 7,
]
]
],
// Параметры запроса
// Напоминание: для получения текущих параметров в контроллере, можно воспользоваться методом request()->map()
'parameters' => [
'iblock_id' => [
// Обязательный параметр
// 'required' => true, // true || false
'type' => 'integer',
// Возможные значения параметра
'possibleValue' => [
'1',
'...',
'50'
],
'description' => 'ID инфоблока'
],
'active' => [
'type' => 'string',
'possibleValue' => [
'Y',
'N'
],
'description' => 'Активность'
],
'name' => [
'type' => 'string',
'description' => 'Имя элемента'
],
'color' => [
'type' => 'string',
'possibleValue' => [
'Белый',
'Красный'
],
'description' => 'Свойство: Цвет'
],
'form' => [
'type' => 'string',
'possibleValue' => [
'Круглый',
'Квадрат'
],
'description' => 'Свойство: Форма'
],
'fields' => [
'type' => 'string',
'possibleValue' => [
'preview_text',
'detail_text',
'preview_picture',
'form'
],
'description' => 'Дополнительные поля'
],
'sort' => [
'type' => 'string',
'description' => 'Сортировка (пример: sort=id:asc,name:asc)'
],
'limit' => [
'type' => 'integer',
'possibleValue' => [
'1',
'...',
'150'
],
'description' => 'Количество (по умолчанию: 10)'
],
'page' => [
'type' => 'integer',
'description' => 'Страница'
]
],
// Пример ответа
// Необходим лишь для документации
// #DOMAIN# и #API# будут автоматически заменены на реальные данные при выводе на экран
// Данный ключ исключен из публичной документации
// 'example' => [
// 'request' => [
// 'url' => 'http://#DOMAIN#/#API#/example/check/?iblock_id=1&sort=id:asc',
// 'response' => [
// 'json' => '{"page":1,"total":3,"items":[{"ID":1,"NAME":"item1"},{"ID":2,"NAME":"item2"},{"ID":3,"NAME":"item3"}]}'
// ]
// ]
// ],
// Настройки для поведения роута в документации
// Данный ключ исключен из публичной документации
'documentation' => [
// Исключить роут
'exclude' => [
// Из документации в административной части сайта
'admin' => false, // true || false
// Из документации в публичной части сайта
'public' => false, // true || false
]
]
],
// Пример роута с использованием переменных в строке
// Доступно начиная с версии 3.4.0
'/example/check/iblock/{{iblockId}}/' => [
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_get',
'parameters' => [
'iblockId' => [
'required' => true,
'type' => 'integer',
'description' => 'ID инфоблока',
],
]
],
'example/check/section/{{sectionId}}' => [
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_get',
'parameters' => [
'sectionId' => [
'required' => true,
'type' => 'integer',
'description' => 'ID раздела',
]
]
],
'example/check/section/{{sectionId}}/{{productId}}/view' => [
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_get',
'parameters' => [
'sectionId' => [
'required' => true,
'type' => 'integer',
'description' => 'ID раздела',
],
'productId' => [
'required' => true,
'type' => 'integer',
'description' => 'ID товара',
],
]
],
],
// Запросы поддерживают все возможные параметры: из строки запроса (GET) и из тела запроса
'POST' => [
'example/check' => [
// 'description' => 'POST',
// Роут отключен
// Клиент получит ответ со статусом: 434 Requested host unavailable
//'active' => false,
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_post',
// Сервер ожидает запрос с типом контента application/json
// Если тип будет отличаться, запрос будет отклонен
'contentType' => 'application/json',
'security' => [
'auth' => [
// 'required' => true,
// 'type' => 'login',
],
'token' => [
'whitelist' => [
// '408f4f2e-d5a6e4a7-06930a16-8301b343'
]
]
],
'parameters' => [
// Параметры: уровень 1
'iblock_id' => [
'required' => true,
'type' => 'integer',
'description' => 'ID инфоблока'
],
'user' => [
'required' => true,
'type' => 'array',
'description' => 'Автор',
// Параметры: уровень 2
'parameters' => [
'id' => [
'required' => true,
'type' => 'integer',
'description' => 'ID'
],
'name' => [
'required' => true,
'type' => 'string',
'description' => 'Имя'
]
]
],
'items' => [
'required' => true,
'type' => 'array',
'description' => 'Массив объектов (элементов)',
'parameters' => [
// Параметры для элемента типа массив
// Правила прописыаются только для одного item, но проверка происходит для каждого объекта/массива
//
// Пример items при запросе:
// "items": [
// {
// "name":"test",
// "color":"blue",
// "preview_text":"Описание анонса"
// },
// {
// "name":"test2",
// "color":"blue",
// "detail_text":"Детальное описание"
// },
// {
// "name":"test3",
// "color":"blue"
// }
// ],
[
'name' => [
'required' => true,
'type' => 'string',
'description' => 'Имя элемента'
],
'preview_text' => [
'type' => 'string',
'description' => 'Описание анонса'
],
'detail_text' => [
'type' => 'string',
'description' => 'Детальное описание'
],
'preview_picture_url' => [
'type' => 'url',
'description' => 'Url изображения анонса'
],
'detail_picture_url' => [
'type' => 'url',
'description' => 'Url детального изображения'
],
'color' => [
'required' => true,
'type' => 'string',
'description' => 'Свойство: Цвет'
],
'form' => [
'type' => 'string',
'description' => 'Свойство: Форма'
]
]
]
]
]
]
],
'PUT' => [
'example/check' => [
// 'description' => 'PUT',
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_put',
'contentType' => 'application/json',
'security' => [
'auth' => [
// 'required' => true,
// 'type' => 'login',
],
],
'parameters' => [
'element_id' => [
'required' => true,
'type' => 'integer',
'description' => 'ID элемента'
],
'name' => [
'type' => 'string',
'description' => 'Имя элемента'
],
'preview_text' => [
'type' => 'string',
'description' => 'Описание анонса'
],
'detail_text' => [
'type' => 'string',
'description' => 'Детальное описание'
],
]
]
],
'PATCH' => [
'example/check' => [
// 'description' => 'PATCH',
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_put',
'contentType' => 'application/json',
'security' => [
'auth' => [
// 'required' => true,
// 'type' => 'login',
],
],
'parameters' => [
'element_id' => [
'required' => true,
'type' => 'integer',
'description' => 'ID элемента'
],
'name' => [
'type' => 'string',
'description' => 'Имя элемента'
],
'preview_text' => [
'type' => 'string',
'description' => 'Описание анонса'
],
'detail_text' => [
'type' => 'string',
'description' => 'Детальное описание'
],
]
]
],
'DELETE' => [
'example/check' => [
// 'description' => 'DELETE',
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_delete',
'security' => [
'auth' => [
// 'required' => true,
// 'type' => 'login',
]
],
'parameters' => [
'element_ids' => [
'required' => true,
'type' => 'array',
'description' => 'ID элементов'
]
]
]
],
'HEAD' => [
'example/check' => [
// 'description' => 'HEAD',
'controller' => '\Artamonov\Rest\Controllers\Native\Example@_head'
]
]
];Last updated
