Общая информация
REST API является простым интерфейсом управления информацией без использования каких-либо дополнительных внутренних прослоек.
Адрес REST-интерфейса
Интерфейс размещается по адресу https://вашсайт/api/, затем указывается версия API, например, https://вашсайт/api/v1.1/.
Версии интерфейса v1 и v1.0 являются синонимами, последняя версия интерфейса 1.1.
Авторизация
Авторизация реализована с использованием токенов, выдаваемых сотруднику через центр администрирования. Токен имеет статус активности, дату начала и дату окончания действия (опционально).
В HTTP-заголовке Authorization указывается токен в формате "Bearer {token}", например:
Authorization: Bearer 615e0465f7c8005b6bbfd00876dfbab9
При авторизации с ошибочным токеном реализована задержка авторизации. После 6 попыток ошибочного доступа осуществляется блокировка доступа IP-адреса с маской подсети "/24" через модуль IP-адреса.
Особенности авторизации в режиме CGI/FastCGI
В режиме CGI и Apache 2.4.13 и старше для включения передачи заголовка Authorization внесите в .htaccess директиву
CGIPassAuth On
В более ранних версиях Apache внесите в .htaccess после RewriteBase /
RewriteCond %{HTTP:Authorization} .+
RewriteCond %{REQUEST_URI} ^/api.*
RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}]
Формат ответа
По умолчанию используется JSON, вы можете его явно указать в HTTP-заголовке запроса
Content-Type: application/json
Допускается использование XML, в этом случае укажите
Content-Type: application/xml
Виды запросов
- GET— используется для извлечения информации;
- POST— используется для создания ресурсов;
- PUT— используется для обновления ресурсов;
- DELETE— используется для удаления ресурсов;
- OPTIONS— используя для получение информации о ресурсе.
Выборка ресурсов с использованием метода GET
Название ресурса указывается в множественном числе, например shops, informationsystem_items, sites и тп., соответствует названию таблицы или названию модели в множественном числе. Связи используют дочерние объекты, заданные в свойстве $_hasMany модели, для которой используется связь. Список ресурсов с примерами доступен по ссылке.
Версия 1.1
Параметры выборки задаются вида $limit, $offset, $orderBy, $count. Количество найденных объектов выводится в HTTP-заголовке "X-Total-Count".
GET /api/v1.1/shops/ — получить все магазины всех сайтов. В результат будут добавлены не более 25 магазинов.
Срез данных
Ограничение выборки и задание смещения производится GET-параметрами $limit (по умолчанию 25) и $offset (по умолчанию 0).
GET /api/v1.1/shops/?$limit=10 — получить первые 10 магазинов.
GET /api/v1.1/shops/?$limit=5&$offset=10&$count=true — получить следующие 5 магазинов, начиная с десятого, а также подсчитать общее количество найденных объектов, количество будет в HTTP-заголовке X-Total-Count
.
Выборка элементов, являющихся дочерними другому элементу:
GET /api/v1.1/sites/1/shops/ — получить все магазины сайта с идентификатором 1. В результат будут добавлены не более 25 магазинов.
Сортировка
GET /api/v1.1/sites/1/shops/?$orderBy=id DESC — получить все магазины сайта с идентификатором 1, упорядоченные в порядке убывания идентификатора.
Задание сортировки происходит GET-параметром $orderBy, в значении содержащего название поле или название поле и направление сортировки (по умолчанию ASC). Опции $orderBy=id и $orderBy=id ASC идентичны. Допускается указание нескольких сортировок, в этом случае указывается в виде массива ?$orderBy[]=field1 DESC&orderBy[]=field2 ASC
GET /api/v1.1/shops/3/ — получить данные о магазине с идентификатором 3.
Развертывание связанных свойств
Вы можете выбрать возврат связанного объекта, вложенного в родительский элемент, для этого используется GET-параметр $expand. Указав поля, которые вы хотите расширить, вы можете попросить сервер получить связанные поля и включить объекты в ответ. Названия свойств указываются в единственном числе через запятую, например $expand=shop_group,shop_currency.
Чтобы расширить дочерние свойства, укажите их через точку, например $expand=shop_group.shop.site,shop_currency:
Версия 1.0
Параметры выборки задаются вида limit, offset, orderBy.
GET /api/v1.0/shops/ — получить все магазины всех сайтов. В результат будут добавлены не более 25 магазинов.
Срез данных
Ограничение выборки и задание смещения производится GET-параметрами limit (по умолчанию 25) и offset (по умолчанию 0).
GET /api/v1.0/shops/?limit=10 — получить первые 10 магазинов.
GET /api/v1.0/shops/?limit=5&offset=10 — получить следующие 5 магазинов, начиная с десятого.
Выборка элементов, являющихся дочерними другому элементу:
GET /api/v1.0/sites/1/shops/ — получить все магазины сайта с идентификатором 1. В результат будут добавлены не более 25 магазинов.
Сортировка
GET /api/v1.0/sites/1/shops/?orderBy=id DESC — получить все магазины сайта с идентификатором 1, упорядоченные в порядке убывания идентификатора.
Задание сортировки происходит GET-параметром orderBy, в значении содержащего название поле или название поле и направление сортировки (по умолчанию ASC). Опции orderBy=id и orderBy=id ASC идентичны. Допускается указание нескольких сортировок, в этом случае указывается в виде массива ?orderBy[]=field1 DESC&orderBy[]=field2 ASC
GET /api/v1.0/shops/3/ — получить данные о магазине с идентификатором 3.
Фильтрация выборки в версиях 1.1 и 1.0
Ограничение выборки осуществляется с помощью передачи GET-параметров, виде параметр=значение, например, выбрать все оплаченные заказы в первом магазине:
GET /api/v1.0/shops/1/shop_orders/?paid=1
Операторы фильтрации, которые указываются по схеме параметр|оператор=значение, позволяют строить сложные запросы, например: ?id|gte=77&amount|lt=100
- ne — "!=" не равно;
- lt — "<" меньше;
- gt — ">" больше;
- lte — "≤" меньше или равно;
- gte — "≥" больше или равно.
Количество задаваемых параметров фильтрации не ограничено.
Создание ресурсов методом POST
POST /api/v1.1/shops/ — создание нового магазина
POST /api/v1.1/shops/1/shop_items/ — создание нового товара в первом магазине
Данные о создаваемом элементе передаются в виде JSON. В ответе будет указан идентификатор созданной записи.
Изменение ресурсов методом PUT
PUT /api/v1.1/shop_items/123/ — редактирование товара с идентификатором 123.
Обновляемые данные передаются в виде JSON.
Вызов методов у ресурсов:
PUT /api/v1.1/shop_orders/17/paid/ — установить оплачено (вызвать метод paid()) у заказа с идентификатором 17.
Удаление ресурсов методом DELETE
DELETE /api/v1.1/shop_items/123/ — удаление товара с идентификатором 123.
DELETE /api/v1.1/shop/1/shop_orders/ — удаление заказов магазина с учетом ограничений выборок, доступны для SELECT.
Получение информации о ресурсе методом OPTIONS
OPTIONS /api/v1.1/shop_items/ — получить информацию о ресурсе shop_items
Вывод ошибок
При возникновении ошибки, в элементе error возвращается code с указанием кода ошибки и message с текстом ошибки.
Примеры запросов
Получение списка заказов первого магазина в формате XML
<?php
header("Content-type: text/html; charset=UTF-8");
require_once('bootstrap.php');
$domain = 'http://site.ru';
$oCore_Http = Core_Http::instance();
$oCore_Http
->clear()
->additionalHeader('Accept', '*/*')
->additionalHeader('Accept-Language', 'ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3')
->additionalHeader('Accept-Encoding', 'gzip, deflate')
->additionalHeader('Authorization', 'Bearer ЗДЕСЬ-УКАЖИТЕ-ТОКЕН')
//->contentType('application/json')
->contentType('application/xml')
->method('GET')
->url($domain . '/api/v1.1/shops/1/shop_orders/?$limit=50')
->execute();
$sContent = $oCore_Http->getDecompressedBody();
echo $sContent;
если необходима печать заголовков ответе, то выполните
var_dump($oCore_Http->getHeaders());
Создание нового магазина для первого сайта, ответ в JSON
<?php
header("Content-type: text/html; charset=UTF-8");
require_once('bootstrap.php');
$domain = 'http://site.ru';
$requestData = json_encode(
array(
'site_id' => 1,
'name' => 'Новый магазин',
'shop_currency_id' => 1,
'email' => 'alexander@site.ru'
)
);
$oCore_Http = Core_Http::instance();
$oCore_Http
->clear()
->additionalHeader('Accept', '*/*')
->additionalHeader('Accept-Language', 'ru-ru,ru;q=0.8,en-us;q=0.5,en;q=0.3')
->additionalHeader('Accept-Encoding', 'gzip, deflate')
->additionalHeader('Authorization', 'Bearer ЗДЕСЬ-УКАЖИТЕ-ТОКЕН')
->contentType('application/json')
//->contentType('application/xml')
->method('POST')
->url($domain . '/api/v1.1/shops/')
->rawData($requestData)
->execute();
$sContent = $oCore_Http->getDecompressedBody();
echo $sContent;
История изменений
Версия 7.0.7
Добавлено развертывание связанных свойств $expand.
Версия 7.0.6
Добавлен подсчет общего количества найденных по запросу элементов, через $count=true, количество будет в HTTP-заголовке X-Total-Count.
Версия 6.9.7
Добавлена возможность вызова методов у полученного элемента при GET-запросе.
Комментарии
Только авторизованные пользователи могут оставлять комментарии.