Как использовать REST API WordPress для получения записей

REST API позволяет получить записи WordPress в формате JSON — например, чтобы показать их во внешнем приложении или на отдельном фронтенде. Для обычных опубликованных записей достаточно отправить GET-запрос к адресу /wp-json/wp/v2/posts. В ответ придёт массив объектов с заголовками, датами, ссылками, анонсами и другим доступным контентом.

Адрес запроса и первый ответ

Если сайт доступен по адресу https://example.com, запрос выглядит так:

https://example.com/wp-json/wp/v2/posts

Откройте адрес в браузере или выполните запрос через командную строку:

curl 'https://example.com/wp-json/wp/v2/posts'

При успешном запросе сервер вернёт JSON-массив. Каждый элемент — отдельная запись. Среди типичных полей есть id, date, slug, link, а также объекты title, excerpt и content. У текстовых полей обычно есть свойство rendered: оно содержит подготовленное к отображению значение, например заголовок или HTML содержимого.

Для конкретной записи используется её числовой ID: /wp-json/wp/v2/posts/123. Если нужно сначала проверить, доступен ли REST API на сайте, откройте https://example.com/wp-json/: корневой адрес обычно возвращает описание API и доступных маршрутов.

Как выбрать нужные записи

Параметры запроса добавляются после знака вопроса. Например, чтобы получить пять последних записей, отсортированных по дате от новых к старым:

https://example.com/wp-json/wp/v2/posts?per_page=5&orderby=date&order=desc

Наиболее полезные параметры:

  • per_page — число записей в ответе. По умолчанию WordPress возвращает 10; максимум для одного запроса — 100.
  • page — номер страницы результатов, начиная с 1.
  • search — поиск по тексту записей, например ?search=wordpress.
  • categories и tags — фильтрация по ID рубрик и меток.
  • author — фильтрация по ID автора.
  • orderby и order — поле и направление сортировки. Например, orderby=date&order=asc.
  • _fields — список нужных полей, чтобы не загружать весь объект записи.

Чтобы узнать ID рубрики или автора, можно запросить соответствующие маршруты, например /wp-json/wp/v2/categories или /wp-json/wp/v2/users. Публичные данные пользователя могут быть ограничены настройками сайта и версией WordPress. В параметрах URL пробелы и специальные символы должны быть закодированы; при формировании запроса в JavaScript эту работу удобно поручить URLSearchParams.

Например, запрос ниже возвращает заголовки, ссылки и анонсы двух записей, найденных по слову:

https://example.com/wp-json/wp/v2/posts?search=wordpress&per_page=2&_fields=id,link,title,excerpt

Параметр _fields сокращает ответ, но перечисленные поля должны соответствовать данным, которые действительно нужны приложению. Если понадобится содержимое записи, добавьте content; для изображения записи — featured_media. Само поле с ID изображения не содержит готовый URL: его можно получить через маршрут медиафайлов /wp-json/wp/v2/media/{id} или использовать в запросе параметр _embed, когда нужны встроенные связанные данные.

Пагинация: как получить весь список

Если записей больше, чем помещается в один ответ, API не возвращает их все сразу. Запросите первую страницу, затем следующие, увеличивая значение page: например, ?per_page=20&page=1, затем ?per_page=20&page=2. В заголовках HTTP-ответа WordPress передаёт X-WP-Total — общее число найденных записей — и X-WP-TotalPages — число страниц с выбранным размером выдачи. Это помогает понять, когда остановить загрузку.

Не запрашивайте весь архив одним запросом: помимо установленного лимита в 100 элементов, крупный ответ увеличивает время загрузки и расход памяти. Для ленты обычно достаточно первой страницы и кнопки «Показать ещё»; для синхронизации всего набора проходите страницы последовательно.

Пример: вывести записи на другом фронтенде

Следующий пример запрашивает пять последних записей и добавляет заголовок и анонс в элемент с ID posts. Создайте такой контейнер в HTML:

<div id="posts"></div>
<script>
const endpoint = new URL('https://example.com/wp-json/wp/v2/posts');
endpoint.search = new URLSearchParams({
  per_page: '5',
  _fields: 'id,link,title,excerpt'
});

const container = document.querySelector('#posts');

fetch(endpoint)
  .then(response => {
    if (!response.ok) {
      throw new Error(`Ошибка API: ${response.status}`);
    }
    return response.json();
  })
  .then(posts => {
    for (const post of posts) {
      const article = document.createElement('article');
      const heading = document.createElement('h2');
      const link = document.createElement('a');
      const excerpt = document.createElement('p');

      link.href = post.link;
      link.textContent = post.title.rendered;
      heading.append(link);

      const excerptDocument = new DOMParser().parseFromString(
        post.excerpt.rendered,
        'text/html'
      );
      excerpt.textContent = excerptDocument.body.textContent.trim();

      article.append(heading, excerpt);
      container.append(article);
    }
  })
  .catch(error => console.error(error));
</script>

Замените https://example.com на адрес своего сайта. Здесь заголовок и анонс выводятся как текст, а не вставляются в страницу через innerHTML. Это снижает риск внедрения HTML из ответа API. Если нужно показать форматированное содержимое записи, оно находится в post.content.rendered; выводить его через innerHTML следует только если вы доверяете источнику и понимаете, какие HTML-теги разрешены.

Публичные записи и доступ к закрытому контенту

Для чтения опубликованных записей обычно не нужны логин и пароль: это публичный контент. Черновики, приватные записи и другие данные, доступные только авторизованному пользователю, требуют аутентификации и соответствующих прав. Не встраивайте пароль, Application Password или другой секрет в JavaScript-код страницы: посетитель сможет увидеть его в исходниках и запросах браузера. Для таких сценариев запрос делают на сервере, где секрет хранится вне публичного кода.

Если фронтенд и WordPress находятся на разных доменах, браузер применяет правила CORS. Запрос может успешно работать из командной строки, но блокироваться браузером, если сервер не разрешает обращения с домена фронтенда. В этом случае настройку доступа нужно проверять на сервере, прокси или CDN; не следует отключать браузерную защиту ради обхода ограничения.

Если запрос не возвращает записи

Сначала откройте URL API напрямую и посмотрите статус и тело ответа. Ответ 404 часто означает неверный адрес, отсутствие маршрута или конфликт с настройками сервера. Если адреса WordPress не работают, проверьте, что REST API не отключён плагином или настройкой безопасности. На сервере без поддержки красивых постоянных ссылок может сработать альтернативная форма маршрута: https://example.com/?rest_route=/wp/v2/posts.

Пустой массив не обязательно означает неисправность: записи могут быть отфильтрованы параметрами, например неверным ID рубрики, или быть неопубликованными. Уберите фильтры и проверьте базовый запрос. Если в браузере возникает ошибка CORS, проверьте её в консоли разработчика и сравните результат с запросом через curl: это помогает отличить проблему разрешений браузера от ответа самого WordPress.

Для стандартного типа записей начните с /wp-json/wp/v2/posts, ограничьте выдачу параметрами и запрашивайте следующие страницы по мере необходимости. Если нужны записи другого типа, его REST-маршрут зависит от регистрации типа записи: для доступа через API у него должна быть включена поддержка REST.

⭐⭐⭐⭐⭐