Розробка REST API у WordPress дозволяє безпечно передавати дані між сайтом, окремим фронтендом та зовнішніми сервісами через JSON. Ви можете використовувати стандартні маршрути WordPress або створити власний endpoint, заздалегідь визначивши структуру даних, методи запиту та правила доступу.

Зміст

У цьому посібнику ви розберетеся, коли потрібен REST API, як спроектувати route, налаштувати permission_callback та вибрати спосіб авторизації. Також розглянемо підключення фронтенду, читання каталогу через API, перевірку помилок, кешування та версіонування з урахуванням обмежень теми, плагінів та встановленої версії WordPress.

Перед змінами працюйте на staging-копії та створіть резервну копію сайту: сумісність рішення необхідно перевіряти у конкретній конфігурації. Будь-який endpoint, який приймає дані, повинен перевіряти права користувача, валідувати вхідні значення та безпечно екранувати висновок.

Роль API серед тем, блоків та плагінів описана в огляд кастомної розробки WordPress. Нижче — проектування маршрутів та доступу.

Коли використовувати REST API WordPress

REST API підходить, коли потрібно отримувати або змінювати дані WordPress з окремої програми, інтерфейсу або зовнішньої системи. Сервер повертає структурований JSON, тому контент можна використовувати незалежно від шаблонів сайту. Якщо завдання повністю вирішується темою і звичайними PHP-шаблонами, додавання API-шару може лише ускладнити архітектуру.

Вбудовані маршрути та свої endpoint

WordPress REST API надає вбудовані маршрути для записів, сторінок, рубрик, коментарів, медіафайлів та інших сутностей, що підтримуються. Наприклад, програма може запросити список опублікованих записів, отримати один запис за ідентифікатором або передати параметри фільтрації та пагінації.

Маршрут, або route, визначає адресу ресурсу. Endpoint пов'язує маршрут з конкретним HTTP-методом та обробником: GET зазвичай використовують для читання, POST – для створення, PUT або PATCH – для зміни, DELETE – для видалення. Один маршрут може обслуговувати кілька операцій.

Починайте з вбудованих маршрутів, якщо їхня структура відповідає завданню. Це зменшує обсяг власного коду та спрощує подальшу підтримку. Для довільного типу запису доступ через API налаштовується окремо: при його реєстрації враховується параметр show_in_rest. Сумісність перевіряйте з використовуваною версією WordPress, темою та плагінами.

WordPress REST API кастомний endpoint потрібний, якщо стандартні ресурси не відображають бізнес-логіку. Наприклад, потрібно об'єднати відомості з кількох сутностей, повернути розрахований статус замовлення або прийняти дані з внутрішньої системи. При цьому не варто створювати власний маршрут лише заради перейменування полів: спочатку оцініть, чи можна використовувати стандартну відповідь чи коректно розширити існуючий ресурс.

Сценарії фронтенду та інтеграцій

WordPress REST API підключення фронтенду має сенс, коли публічний інтерфейс реалізований окремо від WordPress: наприклад, як SPA, мобільний додаток або вітрина на іншому технологічному стеку. WordPress у такій схемі відповідає за зберігання та керування контентом, а фронтенд запитує JSON і самостійно формує сторінки.

Типові сценарії використання:

Передача даних на окремий фронтенд. Редактори працюють в адміністративній панелі, а програма отримує заголовки, тексти, зображення та метадані через API.
Читання каталогу через API. Зовнішня вітрина запитує картки, категорії та доступні характеристики. Склад даних залежить від реалізації каталогу та можливостей його плагіна.
Обмін із зовнішньою системою. CRM, сервіс аналітики або внутрішній кабінет отримує дозволені дані або надсилає зміни до WordPress.
Часткове оновлення інтерфейсу. Окремий блок сайту завантажує актуальні записи без перезавантаження сторінки.

Перед вибором API-архітектури визначте обсяг та частоту запитів, необхідність зміни даних, вимоги до кешування та передбачувані клієнти. Для невеликого контентного сайту REST API може бути надлишковим. Для кількох інтерфейсів, які використовують єдине джерело даних, він допомагає відокремити контент від подання, але вимагає заздалегідь продумати формат відповідей та межі інтеграції.

Спроектуйте маршрут та дані

До написання коду визначте контракт API: адресу маршруту, HTTP-метод, вхідні параметри та структуру JSON-відповіді. Такий підхід спрощує wordpress rest api розробку та допомагає окремо узгодити фронтенд та серверну частину.

Метод, схема та відповідь

Маршрут складається з простору імен та шляху. Наприклад, для каталогу можна використовувати /wp-json/project/v1/catalog, де project/v1 - namespace з версією, а /catalog - route. Endpoint – це поєднання маршруту та конкретного HTTP-методу.

GET - Читання каталогу або окремого запису;
POST - Створення ресурсу або запуск операції;
PUT і PATCH - Повне або часткове оновлення;
DELETE - Видалення ресурсу.

Для окремого фронтенду заздалегідь зафіксуйте назви полів та їх типи. Наприклад, відповідь каталогу може містити items, page, per_page і total. Не передавайте всі поля запису "про всяк випадок": це збільшує обсяг відповіді і може розкрити внутрішні дані.

Якщо очікується великий каталог, передбачте пагінацію, фільтри та стабільне сортування. Для даних, що часто читаються і рідко змінюються, можна планувати кешування GET-відповідей. Версія в namespace дозволяє пізніше випустити project/v2, не змінюючи контракт вже підключеного фронтенду.

Базова реєстрація публічного маршруту читання може мати такий вигляд:

add_action( 'rest_api_init', function () {
    register_rest_route( 'project/v1', '/catalog', array(
        'methods'  => WP_REST_Server::READABLE,
        'callback' => 'project_get_catalog',
        'permission_callback' => '__return_true',
        'args' => array(
            'page' => array(
                'type'    => 'integer',
                'default' => 1,
                'minimum' => 1,
            ),
            'per_page' => array(
                'type'    => 'integer',
                'default' => 20,
                'minimum' => 1,
                'maximum' => 100,
            ),
        ),
    ) );
} );

__return_true допустимо тут лише для справді публічного читання. Для зміни даних або отримання закритих полів потрібен окремий permission_callback з перевіркою можливостей користувача. Перед додаванням коду працюйте на staging-середовищі та зробіть резервну копію. Сумісність необхідно перевіряти з використовуваною версією WordPress, темою та плагінами.

Перевірка вхідних даних

WordPress REST API кастомний endpoint не повинен довіряти параметрам запиту. Спочатку перевірте формат та допустимий діапазон, а потім нормалізуйте значення. Валідація відповідає на запитання «чи можна прийняти дані», а санітарна обробка призводить їх до безпечного вигляду.

Наприклад, рядковий фільтр категорії можна описати так:

'category' => array(
    'type'              => 'string',
    'required'          => false,
    'validate_callback' => function ( $value ) {
        return is_string( $value ) && strlen( $value ) <= 100;
    },
    'sanitize_callback' => 'sanitize_key',
),

Вибирайте функцію обробки за змістом поля: sanitize_text_field() підходить для звичайного тексту, sanitize_key() - для ідентифікаторів та slug, absint() - Для невід'ємних цілих чисел. Параметри SQL не можна вставляти у запит рядковою конкатенацією; використовуйте API WordPress або підготовлені запити.

Відповідь формуйте явно та повертайте через rest_ensure_response() або WP_REST_Response. Числові ідентифікатори наводьте до числа, а HTML включайте тільки тоді, коли він передбачений контрактом. При помилці повертайте WP_Error зі зрозумілим машинним кодом та коректним HTTP-статусом, не розкриваючи шляхи файлів, SQL-запити та інші внутрішні відомості.

До реалізації погодьте приклад запиту та JSON-відповіді. Це особливо важливо, коли виконується wordpress rest api підключення фронтенду: клієнтська команда зможе спиратися на стабільну схему, а не на внутрішній пристрій WordPress.

Налаштуйте права та авторизацію

У WordPress автентифікація визначає, хто надсилає запит, а авторизація — чи дозволено користувачеві виконати конкретну дію. Для кожного маршруту заздалегідь розділіть публічні операції, читання закритих даних та зміну контенту. CORS, nonce і прихований URL власними силами не замінюють перевірку прав.

Публічні та закриті дані

Публічний endpoint підходить для опублікованого каталогу, списку категорій чи іншої інформації, яка вже доступна відвідувачам сайту. У permission_callback такого маршруту можна використовувати __return_true, але якщо розкриття даних дійсно допустимо. Не включайте у відповідь службові поля, внутрішні коментарі, персональні дані та відомості про неопубліковані записи.

Закриті операції потребують підтвердження особи. Вибір способу залежить від розташування клієнта та рівня доступу.

Спосіб авторизації	Сценарій	Обмеження
Cookie authentication та REST nonce	Запити з адміністративної частини або фронтенду WordPress від користувача, що вже увійшов.	Орієнтований на взаємодію всередині сайту. Nonce знижує ризик CSRF, але не замінює перевірку capabilities
Application password	Серверна інтеграція, імпорт даних, зв'язок WordPress з окремим довіреним сервісом	Передавати облікові дані слід лише за HTTPS. Секрет не можна розміщувати у публічному JavaScript або репозиторії
Додаткова схема через плагін	Архітектура з OAuth або іншим протоколом, якщо його потребує інтеграція	Сумісність та безпека залежать від конкретного плагіна, теми та версії WordPress та потребують окремої перевірки

При сценарії "wordpress rest api підключення фронтенда" розрізняйте браузерний та серверний запит. Якщо окремий фронтенд читає відкритий каталог, автентифікація може не знадобитися. Для адміністративних дій безпечніше звертатися до WordPress через серверний шар програми: так application password не потрапить користувачеві. Налаштування CORS дозволяє браузеру звертатися до іншого домену і не надає права на читання або зміну даних.

Перевірка capabilities

Кожен wordpress rest api кастомний endpoint повинен мати осмислений permission_callback. Перевіряйте не роль за назвою, а capability через current_user_can(). Такий підхід враховує стандартну систему прав WordPress та зміни, внесені плагінами.

Вибирайте здатність до операції. Для редагування конкретного запису передайте його ID на перевірку current_user_can('edit_post', $post_id). Для видалення використовуйте відповідне право видалення, а для загальних адміністративних налаштувань - capability, дійсно необхідну для цієї операції. Не застосовуйте manage_options автоматично до всіх закритих маршрутів: це може невиправдано обмежити редакторів та одночасно приховати неточну модель доступу.

Якщо доступ заборонено, повертайте WP_Error зі зрозумілим кодом та коректним HTTP-статусом, зазвичай 401 для відсутньої автентифікації або 403 для користувача без необхідних прав. Не розкривайте у повідомленні токени, SQL-запити, шляхи сервера та інші внутрішні відомості.

Дозволяйте публічний доступ лише після перевірки складу JSON-відповіді.
Перевіряйте здатність кожної операції, включаючи читання чернеток і зміну записів.
Валідуйте вхідні параметри та очищайте дані перед збереженням.
Екрануйте дані під час наступного виведення у відповідному HTML-, URL- або іншому контексті.
Передавайте секрети лише за HTTPS та зберігайте їх поза клієнтським кодом.
Видавайте інтеграції окремі облікові дані з мінімально необхідними правами та можливістю відкликання.
Перевіряйте реалізацію на staging-середовищі після резервного копіювання; сумісність теми, плагінів та версії WordPress не можна вважати гарантованою без перевірки.

Перевірте роботу endpoint

Перевіряйте endpoint на тестовому середовищі до підключення робочого фронтенду чи зовнішньої системи. Переконайтеся, що маршрут приймає HTTP-метод, повертає валідний JSON, коректно обробляє параметри і не розкриває дані користувачеві без необхідних прав.

Коди відповіді та помилки

Почніть із позитивного сценарію: надішліть коректний запит із дозволеними параметрами та відповідними обліковими даними. Перевірте не тільки тіло відповіді, а й HTTP-статус, заголовок Content-Type, структуру JSON та наявність обов'язкових полів. Клієнтський код не повинен залежати від випадкового порядку полів або тексту повідомлення про помилку.

Потім послідовно відтворіть помилкові запити:

без авторизації та з недійсними обліковими даними;
від користувача, якому бракує прав;
із пропущеним обов'язковим параметром;
з невірним типом, форматом чи значенням параметра;
з неіснуючим ідентифікатором об'єкта;
з непідтримуваним HTTP-методом;
з пошкодженим JSON у запиті.

Код 400 зазвичай вказує на некоректний запит, 401 - на відсутність підтвердженої авторизації, 403 - на недостатні права, 404 - на невідомий маршрут або ресурс, 405 - на метод, що не підтримується. Помилка 500 потребує перевірки серверної логіки. Фактичний статус може залежати від реалізації endpoint, плагінів безпеки, веб-сервера та проксі, тому перевіряйте реальну відповідь конкретної конфігурації.

У endpoint користувача повертайте контрольовані помилки, наприклад через об'єкт WP_Error зі зрозумілим машинним кодом, повідомленням і HTTP-статусом. Не поміщайте у відповідь SQL-запити, шляхи файлів, токени, стек викликів та інші внутрішні відомості. Для wordpress rest api підключення фронтенда передбачте обробку тайм-ауту, невалідного JSON та відповіді без очікуваних полів, а не лише успішного статусу.

Логи та тестове середовище

Зміни спочатку розгортайте на staging-копії сайту після створення резервної копії. Сумісність не можна вважати гарантованою без перевірки версії WordPress, активної теми, плагінів, PHP та налаштувань сервера. Особливо важливо повторити конфігурацію кеша, постійних посилань та засобів захисту, що впливають на запити REST.

Для діагностики на тестовому середовищі можна тимчасово включити журнал WordPress. Не виводьте технічні помилки відвідувачу і не залишайте режим налагодження включеним на робочому сайті. Файл журналу здатний містити персональні дані, параметри запитів та фрагменти конфігурації, тому обмежте доступ до нього та видаліть діагностичні записи після перевірки.

У логах фіксуйте час запиту, route, HTTP-метод, статус та внутрішній ідентифікатор операції. Паролі, application password, cookie, заголовок Authorization та повний вміст персональних даних не можна записувати. Якщо запит проходить через окремий фронтенд, зіставляйте його журнал із логами WordPress за безпечним ідентифікатором.

Для сценарію читання каталогу додатково перевірте порожню вибірку, пагінацію, фільтри, великий доступний обсяг даних та поведінку кеша. Після виправлення повторіть набір запитів: успішний результат не підтверджує, що обмеження доступу та обробка помилок залишилися коректними.

Підтримка та обмеження

Після запуску endpoint розглядайте його як стабільний контракт між WordPress та зовнішньою системою. Зміна назви поля, формату дати або структури JSON може порушити роботу фронтенду, мобільного додатка або імпорту. Тому підтримка API включає контроль сумісності, версіонування, кешування та спостереження за помилками.

Версіонування та сумісність

Вказуйте версію у просторі імен маршруту, наприклад project/v1. Якщо потрібна несумісна зміна, створіть project/v2, а стару версію тимчасово збережіть для клієнтів, що діють. Додавання необов'язкового поля зазвичай безпечніше, ніж видалення або перейменування використовуваного.

Зафіксуйте контракт endpoint у документації: HTTP-метод, параметри, обов'язкові поля, структуру JSON, можливі коди відповіді та вимоги до доступу. Вкажіть окремо, які значення можуть бути порожніми. Це допомагає відрізнити помилку інтеграції від коректної відповіді без даних.

Не обіцяйте сумісність без перевірки версії WordPress, активної теми та плагінів. Розширення можуть реєструвати власні route, змінювати типи записів, обмежувати REST API або впливати на формат даних. Оновлення спочатку перевіряйте на staging-копії з актуальною конфігурацією та резервною копією.

Об'єм даних та кешування

Для читання каталогу через API не передавайте весь масив товарів однією відповіддю. Використовуйте пагінацію, фільтри та вибір лише необхідних полів. Чим більше записів та пов'язаних даних запитує клієнт, тим вище навантаження на базу і тим довше формується відповідь.

При підключенні окремого фронтенду заздалегідь визначте стратегію кешування. Публічні каталожні дані можна кешувати на стороні клієнта, CDN або сервера, якщо допустима невелика затримка оновлення. Персональні відповіді та дані, що залежать від прав користувача, не можна змішувати у загальному публічному кеші.

Продумайте інвалідування кешу: за часом, після зміни запису або через окремий механізм сповіщень. Без цього фронтенд може показувати застарілі ціни, залишки чи публікації. Конкретний спосіб залежить від інфраструктури, частоти оновлень та допустимого періоду неактуальності.

Як оцінити обсяг підтримки

Критерій	Що перевірити	Можливе обмеження
Обсяг даних	Число записів, розмір JSON, частоту запитів	Потрібні пагінація, фільтри та оптимізація запитів
Рівень доступу	Чи є публічні, службові та персональні дані	Різні відповіді не можна обслуговувати однією політикою кешування
Кешування	Як швидко зміни мають з'являтися на фронтенді	Тривалий кеш знижує актуальність, короткий - економить менше ресурсів
Версіонування	Скільки клієнтів залежить від поточного контракту	Старі версії доведеться підтримувати у перехідний період

Після оновлення контролюйте журнал помилок, частку відповідей 4xx і 5xx, час відповіді та випадки порожніх або несподівано великих JSON-відповідей. Корисно також зберігати перелік споживачів API та використовуваних ними версій маршрутів. Так ви зможете заздалегідь попередити команди про виведення старого кінця з експлуатації.

WordPress REST API підходить для багатьох інтеграцій, але не скасовує проектування продуктивності. При великому каталозі, складних зв'язках між сутностями або інтенсивною синхронізацією може знадобитися серверне кешування, фонові завдання або окремий інтеграційний шар. Рішення вибирайте після перевірки реальної структури даних та навантаження, а не лише за наявністю готового інтерфейсу REST.

Офіційна документація: REST API WordPress і авторизація запитів.

«Перед інтеграцією через REST API я пропоную скласти таблицю прав: хто читає дані, хто змінює їх і як відгукується доступ. Успішна відповідь API ще не означає правильного захисту даних.»

Богдан Рябошапка, засновник та автор блогу Web Raketa. Коментар автора.