REST API является простым интерфейсом управления информацией без использования каких-либо дополнительных внутренних прослоек.
Интерфейс размещается по адресу https://вашсайт/api/, затем указывается версия API, например, https://вашсайт/api/v1/.
Авторизация реализована с использованием токенов, выдаваемых сотруднику через центр администрирования. Токен имеет статус активности, дату начала и дату окончания действия (опционально).
В HTTP-заголовке Authorization указывается токен в формате "Bearer {token}", например:
Authorization: Bearer 615e0465f7c8005b6bbfd00876dfbab9
В режиме 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 /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.
Ограничение выборки осуществляется с помощью передачи GET-параметров, виде параметр=значение, например, выбрать все оплаченные заказы в первом магазине:
GET /api/v1.0/shops/1/shop_orders/?paid=1
Операторы фильтрации, которые указываются по схеме параметр|оператор=значение, позволяют строить сложные запросы, например: ?id|gte=77&amount|lt=100
Количество задаваемых параметров фильтрации не ограничено.
POST /api/v1.0/shops/ — создание нового магазина
POST /api/v1.0/shops/1/shop_items/ — создание нового товара в первом магазине
Данные о создаваемом элементе передаются в виде JSON. В ответе будет указан идентификатор созданной записи.
PUT /api/v1.0/shop_items/123/ — редактирование товара с идентификатором 123.
Обновляемые данные передаются в виде JSON.
Вызов методов у ресурсов:
PUT /api/v1.0/shop_orders/17/paid/ — установить оплачено (вызвать метод paid()) у заказа с идентификатором 17.
DELETE /api/v1.0/shop_items/123/ — удаление товара с идентификатором 123.
DELETE /api/v1.0/shop/1/shop_orders/ — удаление заказов магазина с учетом ограничений выборок, доступны для SELECT. * с версии 6.9.9
OPTIONS /api/v1.0/shop_items/ — получить информацию о ресурсе shop_items
При возникновении ошибки, в элементе error возвращается code с указанием кода ошибки и message с текстом ошибки.
<?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.0/shops/1/shop_orders/?limit=50') ->execute(); $sContent = $oCore_Http->getDecompressedBody(); echo $sContent;
если необходима печать заголовков ответе, то выполните
var_dump($oCore_Http->getHeaders());
<?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.0/shops/') ->rawData($requestData) ->execute(); $sContent = $oCore_Http->getDecompressedBody(); echo $sContent;
Для метода PUT доступно только изменение одной конкретной записи? Можно ли изменить сразу несколько по значению первичного ключа, к примеру?
Значений изменить можно несколько, но у одного элемента!
То есть методом PUT обратиться за изменением записей можно только для одного элемента, указав его конкретный идентификатор в строке адреса? Обратиться сразу к нескольким, добавив условия отбора, нельзя?
Вы можете выбрать несколько элементов с фильтрацией, пример дан выше, а изменение PUT-запросом только одного элемента.
Правильно ли я понимаю, что это доступно только сотрудникам-администраторам?
REST-запросы доступны из клиентского раздела при указании токена, см. https://www.hostcms.ru/documentation/modules/restapi/add-token/
Сотрудники-администраторы выдают только токены.
Я имел в виду другое. До тех пор, пока токен не был выдан пользователю с правами администратора, запрос к REST API возвращал сообщение с ошибкой о запрете доступа.
Запрет не пользователю, запрет на запросы без правильного токена.