RESTful-веб-сервис

Если REST — это набор архитектурных принципов, то RESTful-сервис — их воплощение в конкретном API, к которому обращаются сайт, мобильное приложение или CRM. На практике прилагательное «RESTful» означает, что API следует основным соглашениям: понятные адреса, правильные методы, честные коды ответов.

Из чего состоит сервис

• Адреса ресурсов: /products — коллекция, /products/42 — один товар, /products/42/reviews — вложенная коллекция.
• Методы: GET читает, POST создаёт, PUT и PATCH меняют, DELETE удаляет.
• Коды ответа: 200 — успех, 201 — создано, 400 — ошибка в запросе, 401 и 403 — нет доступа, 404 — ресурса нет, 422 — данные не прошли проверку.
• Формат: обычно JSON в теле и заголовок Content-Type.
• Служебное: постраничный вывод, фильтры через параметры, версия в адресе или заголовке, авторизация по токену.

Пример маршрута в WordPress

В WordPress встроен REST API, и свои адреса добавляются через хук rest_api_init. Маршрут ниже отдаёт остаток товара по артикулу:

add_action( 'rest_api_init', function () {
    register_rest_route( 'shop/v1', '/stock/(?P<sku>[\w-]+)', [
        'methods'             => 'GET',
        'callback'            => 'shop_get_stock',
        'permission_callback' => '__return_true',
    ] );
} );

function shop_get_stock( WP_REST_Request $request ) {
    $sku = sanitize_key( $request['sku'] );
    return [ 'sku' => $sku, 'qty' => (int) get_option( "stock_$sku", 0 ) ];
}

Запрос GET /wp-json/shop/v1/stock/sofa-204 вернёт JSON. Параметр permission_callback обязателен: для чтения публичных данных подойдёт __return_true, для записи нужна проверка прав.

Насколько сервис действительно RESTful

Для оценки удобна модель зрелости Леонарда Ричардсона. Уровень 0 — всё идёт одним POST на один адрес. Уровень 1 — появились отдельные ресурсы. Уровень 2 — используются методы и коды HTTP по назначению; на нём находится большинство хороших публичных API. Уровень 3 — ответы содержат ссылки на связанные действия, и клиент может «ходить» по API, как по сайту. Проектированием и подключением таких сервисов занимается разработка API и интеграций.