WordPress REST Endpoints

Introduction

WordPress REST API provides an interface for applications to interact with your WordPress site over HTTP. The REST API is a powerful tool that allows developers to retrieve, create, update, and delete WordPress content from external applications or scripts.

In this guide, we'll explore WordPress REST endpoints - the URLs that provide access to your WordPress data. We'll learn how to use existing endpoints, create custom ones, and implement practical applications that leverage this powerful feature.

What are REST Endpoints?

REST (Representational State Transfer) endpoints are specific URLs that respond to HTTP requests. In WordPress, these endpoints follow a consistent pattern and allow you to interact with various WordPress resources like posts, pages, users, and more.

A WordPress REST endpoint typically looks like this:

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

Let's break down the structure:

https://example.com/ - Your WordPress site URL
wp-json/ - The REST API base
wp/v2/ - The namespace and version
posts - The route (resource type)

Core WordPress REST API Endpoints

WordPress includes many built-in endpoints that you can use right away. Here are some commonly used ones:

Endpoint	Description
`/wp/v2/posts`	Access posts
`/wp/v2/pages`	Access pages
`/wp/v2/users`	Access users
`/wp/v2/categories`	Access categories
`/wp/v2/tags`	Access tags
`/wp/v2/comments`	Access comments
`/wp/v2/media`	Access media items

Example: Fetching Posts

Here's how to fetch posts using JavaScript:

javascript
// Using fetch API to get the 3 most recent posts
fetch('https://example.com/wp-json/wp/v2/posts?per_page=3')
  .then(response => response.json())
  .then(posts => {
    console.log(posts);
    // Do something with the posts
    posts.forEach(post => {
      console.log(post.title.rendered);
      console.log(post.content.rendered);
    });
  })
  .catch(error => console.error('Error:', error));

The response will be an array of post objects with properties like id, title, content, excerpt, author, featured_media, etc.

Working with API Parameters

WordPress REST API endpoints accept various parameters to filter, sort, and paginate results.

Common Parameters

per_page: Number of items to return (default: 10, max: 100)
page: Current page of results
search: Search term
order: Sort order (asc/desc)
orderby: Field to order by (date, title, id, etc.)

Example: Filtered Query

javascript
// Fetch published posts from a specific category, ordered by title
const apiUrl = 'https://example.com/wp-json/wp/v2/posts?status=publish&categories=42&orderby=title&order=asc';

fetch(apiUrl)
  .then(response => response.json())
  .then(posts => {
    console.log(`Found ${posts.length} posts`);
    // Process posts...
  });

Authentication for Protected Endpoints

Some endpoints require authentication, especially for creating, updating, or deleting content. WordPress REST API supports several authentication methods:

Cookie Authentication (for logged-in users)
OAuth 1.0a
Application Passwords (WordPress 5.6+)
JWT Authentication (with plugins)

Using Application Passwords

Since WordPress 5.6, you can use Application Passwords for API authentication:

Go to your WordPress profile page
Scroll to "Application Passwords"
Create a new application password

Then use it in your API requests:

javascript
const username = 'your_username';
const appPassword = 'xxxx xxxx xxxx xxxx xxxx xxxx';

fetch('https://example.com/wp-json/wp/v2/posts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + btoa(username + ':' + appPassword)
  },
  body: JSON.stringify({
    title: 'New Post via REST API',
    content: 'This post was created using the WordPress REST API.',
    status: 'publish'
  })
})
.then(response => response.json())
.then(post => console.log('Post created:', post))
.catch(error => console.error('Error:', error));

Creating Custom REST Endpoints

One of the most powerful features is the ability to create your own custom endpoints. This allows you to expose specific data or functionality through the API.

Basic Custom Endpoint

Here's how to register a simple custom endpoint that returns "Hello World":

php
<?php
add_action('rest_api_init', function () {
  register_rest_route('my-plugin/v1', '/hello', [
    'methods' => 'GET',
    'callback' => 'my_hello_world_endpoint',
    'permission_callback' => '__return_true'
  ]);
});

function my_hello_world_endpoint() {
  return [
    'message' => 'Hello World!',
    'time' => current_time('mysql')
  ];
}

This creates an endpoint at: https://example.com/wp-json/my-plugin/v1/hello

Custom Endpoint with Parameters

Let's create a more useful endpoint that returns posts by a specific author:

php
<?php
add_action('rest_api_init', function () {
  register_rest_route('my-plugin/v1', '/author-posts/(?P<id>\d+)', [
    'methods' => 'GET',
    'callback' => 'get_author_posts',
    'args' => [
      'id' => [
        'validate_callback' => function($param) {
          return is_numeric($param);
        }
      ],
    ],
    'permission_callback' => '__return_true'
  ]);
});

function get_author_posts($request) {
  $author_id = $request['id'];
  
  $posts = get_posts([
    'author' => $author_id,
    'posts_per_page' => 5,
  ]);
  
  if (empty($posts)) {
    return new WP_Error(
      'no_posts_found',
      'No posts found for this author',
      ['status' => 404]
    );
  }
  
  $formatted_posts = [];
  
  foreach ($posts as $post) {
    $formatted_posts[] = [
      'id' => $post->ID,
      'title' => $post->post_title,
      'excerpt' => $post->post_excerpt,
      'link' => get_permalink($post->ID)
    ];
  }
  
  return $formatted_posts;
}

Now you can access: https://example.com/wp-json/my-plugin/v1/author-posts/1

Secure REST API Endpoints

When creating custom endpoints, always implement proper security:

Use permission_callback to control access
Validate and sanitize input data
Follow the principle of least privilege

Here's an endpoint that requires user authentication:

php
<?php
add_action('rest_api_init', function () {
  register_rest_route('my-plugin/v1', '/user-data', [
    'methods' => 'GET',
    'callback' => 'get_user_data',
    'permission_callback' => function() {
      return current_user_can('read');
    }
  ]);
});

function get_user_data() {
  $current_user = wp_get_current_user();
  
  return [
    'id' => $current_user->ID,
    'name' => $current_user->display_name,
    'email' => $current_user->user_email,
    'roles' => $current_user->roles
  ];
}

Real-World Application: Building a React Dashboard

Let's put everything together by creating a simple React dashboard that displays WordPress content via REST API:

First, register a custom endpoint that returns dashboard data:

php
<?php
add_action('rest_api_init', function () {
  register_rest_route('dashboard/v1', '/stats', [
    'methods' => 'GET',
    'callback' => 'get_dashboard_stats',
    'permission_callback' => function() {
      return current_user_can('edit_posts');
    }
  ]);
});

function get_dashboard_stats() {
  // Get counts
  $post_count = wp_count_posts();
  $comment_count = wp_count_comments();
  $user_count = count_users();
  
  // Get recent comments
  $recent_comments = get_comments([
    'number' => 5,
    'status' => 'approve'
  ]);
  
  $formatted_comments = [];
  foreach ($recent_comments as $comment) {
    $formatted_comments[] = [
      'id' => $comment->comment_ID,
      'author' => $comment->comment_author,
      'content' => wp_trim_words($comment->comment_content, 10),
      'post_id' => $comment->comment_post_ID,
      'post_title' => get_the_title($comment->comment_post_ID),
      'date' => $comment->comment_date
    ];
  }
  
  return [
    'counts' => [
      'posts' => $post_count->publish,
      'pages' => wp_count_posts('page')->publish,
      'comments' => $comment_count->approved,
      'users' => $user_count['total_users']
    ],
    'recent_comments' => $formatted_comments
  ];
}

Now, here's a React component that consumes this API:

jsx
import React, { useState, useEffect } from 'react';

function Dashboard() {
  const [isLoading, setIsLoading] = useState(true);
  const [stats, setStats] = useState(null);
  const [error, setError] = useState(null);
  
  useEffect(() => {
    // Replace with your WordPress site URL
    const apiUrl = 'https://example.com/wp-json/dashboard/v1/stats';
    
    // Get the nonce from WordPress if you're using cookie auth
    const wpNonce = document.querySelector('#_wpnonce')?.value || '';
    
    fetch(apiUrl, {
      credentials: 'same-origin',
      headers: {
        'X-WP-Nonce': wpNonce
      }
    })
      .then(response => {
        if (!response.ok) {
          throw new Error('API request failed');
        }
        return response.json();
      })
      .then(data => {
        setStats(data);
        setIsLoading(false);
      })
      .catch(err => {
        setError(err.message);
        setIsLoading(false);
      });
  }, []);
  
  if (isLoading) return <div>Loading dashboard data...</div>;
  if (error) return <div>Error: {error}</div>;
  if (!stats) return <div>No data available</div>;
  
  return (
    <div className="dashboard">
      <h2>Site Statistics</h2>
      
      <div className="stats-grid">
        <div className="stat-box">
          <h3>Posts</h3>
          <div className="stat-count">{stats.counts.posts}</div>
        </div>
        
        <div className="stat-box">
          <h3>Pages</h3>
          <div className="stat-count">{stats.counts.pages}</div>
        </div>
        
        <div className="stat-box">
          <h3>Comments</h3>
          <div className="stat-count">{stats.counts.comments}</div>
        </div>
        
        <div className="stat-box">
          <h3>Users</h3>
          <div className="stat-count">{stats.counts.users}</div>
        </div>
      </div>
      
      <h2>Recent Comments</h2>
      <ul className="comment-list">
        {stats.recent_comments.map(comment => (
          <li key={comment.id} className="comment-item">
            <strong>{comment.author}</strong> on "{comment.post_title}"
            <p>{comment.content}</p>
            <small>{new Date(comment.date).toLocaleDateString()}</small>
          </li>
        ))}
      </ul>
    </div>
  );
}

export default Dashboard;

This example demonstrates how to build a dynamic dashboard using a custom WordPress REST endpoint and React.

Best Practices for Working with REST Endpoints

Cache API Responses: For better performance, especially for data that doesn't change frequently.
Use Proper HTTP Methods: GET for retrieving, POST for creating, PUT/PATCH for updating, DELETE for removing.
Handle Errors Gracefully: Always check for error responses and provide user feedback.
Understand Pagination: For large datasets, implement proper pagination in your requests and UI.
Secure Your Endpoints: Always use permission callbacks to verify user access.
Rate Limiting: Consider implementing rate limiting for public endpoints.
Documentation: Document your custom endpoints for other developers.

Summary

WordPress REST endpoints provide a powerful way to interact with WordPress data programmatically. We've covered:

What REST endpoints are and how they work in WordPress
Using core WordPress REST API endpoints
Working with API parameters to filter and customize results
Authentication methods for protected endpoints
Creating custom REST endpoints for specialized functionality
Security best practices for REST API development
A practical example of building a React dashboard using custom endpoints

The WordPress REST API opens up endless possibilities for building modern applications that interact with your WordPress site. From headless WordPress setups to mobile apps and custom admin interfaces, mastering REST endpoints is an essential skill for WordPress developers.

Additional Resources

Exercises

Create a custom REST endpoint that returns the 5 most popular posts based on comment count or view count.
Build a simple JavaScript app that fetches and displays your WordPress posts with a filter dropdown.
Extend the WordPress REST API to include custom fields from ACF (Advanced Custom Fields) in post responses.
Create a custom endpoint that requires specific user capabilities to access.
Build a React or Vue component that uses the WordPress REST API to create a live search feature.

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)

Introduction​

What are REST Endpoints?​

Core WordPress REST API Endpoints​

Example: Fetching Posts​

Working with API Parameters​

Common Parameters​

Example: Filtered Query​

Authentication for Protected Endpoints​

Using Application Passwords​

Creating Custom REST Endpoints​

Basic Custom Endpoint​

Custom Endpoint with Parameters​

Secure REST API Endpoints​

Real-World Application: Building a React Dashboard​

Best Practices for Working with REST Endpoints​

Summary​

Additional Resources​

Exercises​