Title: Using the WordPress REST API
Author: Jonathan Bossenger
Published: 17 February 2023
Last modified: 23 January 2024

---

# Using the WordPress REST API

The WordPress REST API provides an interface for applications to interact with your
WordPress site by sending and receiving data as JSON (JavaScript Object Notation)
objects. It is the foundation of the WordPress Block Editor.

However, it also provides a more predictable and structured way to interact with
your site’s content than using admin-ajax. In this session, you will learn how to
use the WP REST API in place of using admin-ajax, in order to interact with existing
WordPress data.

## Learning outcomes

 1. Identify the key elements of the WordPress REST API
 2. Use the WordPress REST API global parameters to filter data
 3. Use the Backbone.js client to interact with the WP REST API
 4. Replace an admin-ajax example with a REST API example

## Comprehension questions

 1. What does REST stand for?
 2. What is the difference between a REST API route and an endpoint?
 3. Name the global parameter that allows you to filter which fields are returned from
    a REST API request.
 4. What is the name of the Backbone client data type that’s used to fetch a group 
    of posts from the REST API?

View the video transcript

Hey there, and welcome to Learn WordPress.

In this tutorial, you’re going to learn about the WordPress REST API, and how to
use it in your projects. You will learn about key REST API concepts like routes,
endpoints and global parameters, as well as how to use it in place of something 
like admin-ajax.

The WordPress REST API provides an interface for applications to interact with a
WordPress site. These applications could be WordPress plugins, themes, or custom
applications that need to access WordPress site data. One of the most well known
implementations of the REST API is the Block Editor, which is a JavaScript application
that interacts with WordPress data through the REST API.

An API is an application programming interface. It’s a set of functions that allow
applications to interact with each other. WordPress has many different API’s, the
REST API is just one of them. Rest stands for Representational State Transfer, which
is a software architectural style that describes a uniform interface between physically
separate components. At its core, the WordPress REST API provides REST endpoints
or URLs, which represent the posts, pages taxonomies, and other built in WordPress
data types. Your code can send and receive data as JavaScript Object Notation, or
JSON to these endpoints to query, modify and create content on your site. Let’s 
dive into some of these concepts to understand them better.

In the context of the WordPress REST API, a route is a URI which can be mapped to
different HTTP methods. An HTTP method is the type of request that’s made whenever
you interact with anything on the web. For example, when you browse to a URL on 
the web, a GET request is made to the server to request the data. When you submit
a form, a POST request is made, which passes the submitted form data to the web 
server. The mapping of individual HTTP methods to a route is known as an endpoint.

Let’s look at some examples of routes and endpoints. If you open a browser and go
to the /wp-json/ URL of your local WordPress install, you will be making a GET request
to that URI. The data returned is a JSON response showing what routes are available,
and what endpoints are available within each route. By default, your browser will
display the JSON data in its raw data format. To convert it to a more readable format,
you can use a browser extension like JSON formatter for Chrome, basic JSON format
for Firefox, or JSON Peep for Safari. In this example, /wp-json/ is a route and 
when that route receives a GET request, it’s handled by the endpoint which displays
the data. This data is what is known as the index for the WordPress REST API. By
contrast, the /wp-json/wp/v2/posts/ route offers a GET endpoint, which returns a
list of posts, but also a POST endpoint. If you are an authenticated user, and you
submit the right data via a POST request to this route, the request is handled by
the endpoint which creates new posts. Typically, the same route will have different
endpoints for different HTTP methods, including GET for fetching data, POST for 
creating data, and DELETE for deleting data.

The WordPress REST API includes a number of global parameters which control how 
the API handles the request and response handling. These operate at a layer above
the actual resources themselves, and are available on all resources. Global parameters
are implemented on the REST API routes as query string parameters. Query strings
start with a question mark and are followed by a series of key value pairs separated
by an ampersand. Take a look at the /wp/v2/posts/ route you looked at earlier. As
you can see, the default is to return all the available fields for a post. However,
if you update the route by adding the fields global parameter, question mark, _fields,
and then specify the fields you want to return. In this case, author, id, excerpt,
title and link, you will see that only the fields you have requested to be returned
in the response are made available.

The WordPress REST API also supports pagination and ordering of results. Pagination
is handled by the per_page, page, and offset parameters. For example, you can update
the post route to return only five posts per page by adding the per_page parameter
to the route. It is also possible to order the results using the order and order_by
parameters. For example, you can update the post route to order by post title in
descending order.

By default, the WordPress REST API uses the same cookie based authentication method
as when you log into the WordPress dashboard. So for REST API endpoints that require
a valid user, if the authentication cookie’s present, the request is authenticated.
However, it’s also possible to use Application passwords, JSON web tokens, and OAuth
1.0. to authenticate requests. We will cover these authentication methods in a future
tutorial.

One of the biggest benefits of using the REST API in your plugins is that you can
replace your admin-ajax requests using less code and making your requests more secure.
To see this in action, let’s take a look at a simplified example.

In this code, the plugin adds a menu page to the WordPress dashboard. The page has
a button and a text area. And when the button is clicked, an Ajax request is made
to get the most recent posts and display the titles in the text area. Besides the
functionality to render the admin page, this is what the code looks like to implement
Ajax. First in the wp_learn_rest_enqueue script function, you need to use the wp_localize_script
function to pass the Ajax URL to the wp_learn_ajax object so that it’s available
when the script is loaded. Note that in this example, there’s no implementation 
of a nonce for security, but it is recommended for a production plugin. Then you
need to add a callback function to process the AJAX request by hooking into a wp_ajax_
action hook.

On the JavaScript side, some JavaScript will be needed to handle the click event
on the button and make the AJAX request. Historically, this is usually handled using
some jQuery. So what would this look like if you were using the WordPress REST API?

First of all, you don’t need to pass that Ajax URL anyway, so we can remove that
code from the enqueue script function.

We also won’t be processing an Ajax request, so we can remove the wp_learn_ajax_fest_post
function and associated hook. Finally, we can remove the button and add one to load
post via the REST API.

WordPress ships with a Backbone JavaScript client for making direct requests to 
the WordPress REST API. This provides an interface for the WordPress REST API by
providing backbone models and collections for all endpoints exposed through the 
API. To ensure that your code is able to use the backbone JS client, you may need
to update your plugin’s JavaScript dependencies from jQuery to wp-api. So we can
just change this to wp-api. This will ensure that your plugin’s JavaScript code 
is only loaded after the REST API JavaScript client is loaded. So you can use it
in your plugin.

In the JavaScript file, first, you can delete the jQuery Ajax related code. Then
you’ll want to start by registering a click event handler for the New button.

So we can do something like const load posts by REST button. And we’ll say document,
get element by ID. And we will pass in the Learn REST API button ID of the element.
And then we want to just do a check. Just to make sure that we’re only running our
code if that button exists. And then we can say load posts by REST button. Add EventListener.
Add that in the click event. And register the callback function to fire when the
button is clicked.

Then in this new event handler function, you can use the WP API client by accessing
it from the global WP object to create a new collection of posts.

You can say const allPosts, new API collections posts.

At this point allPosts is simply an empty collection. So you will need to fetch 
the posts by calling the fetch method on the collection.

So allPosts, fetch.

The fetch method returns a promise. So you can chain a done method to handle the
response to implement a callback function, which will accept the response from the
API request.

Done and then a callback function

You can specify a post argument in this callback function to accept the response
from the API request.

So here we can say posts.

Now you can loop through the post object using the forEach method and access each
post individually.

Say, posts for each. Now a callback function and we can pass the individual post
to post as an argument.

Finally, you can add the post title to the text area. First, you need to create 
an instance of the text area before the forEach loop. And then append the post title
to the text areas value property inside the forEach loop.

So we’ll start with const text area. So document get element by ID. And its ID is
termed pillar in posts.

Got that, and then inside the for each loop, we can say text area dot value, and
then append it to the existing value and append post title rendered. And then also
append a newline character. So they’re not all next to each other.

Let’s see what this looks like when we refresh this page on the front end.

And let’s load posts via REST.

The great advantage of using the WordPress REST API and the Backbone js JavaScript
client is that you can use the same client over and over again. For example, if 
you wanted to fetch users, you could simply create a new collection of users to 
fetch them. To do this via admin-ajax, you’ll either need a new admin-ajax handler
function, or you’d need to update your existing function to accept a parameter to
determine what to fetch.

The other advantage is that the API client handles nonce checking for you. With 
admin-ajax, you have to specify this yourself and check it in your handler function.
So using the REST API, and the JavaScript client makes your requests more secure.

This tutorial just scratches the surface of what is possible with the WordPress 
REST API. To learn more about how it works, how to use it, and how to extend it,
check out the WP REST API handbook documentation in the developer resources on wordpress.
org.

Happy coding

## Introduction

Hey there, and welcome to Learn WordPress.

In this tutorial, you’re going to learn about the WordPress REST API, and how to
use it in your projects.

You will learn about key WP REST API concepts like routes, endpoints and global 
parameters, as well as how to use it in place of something like admin-ajax.

The WordPress REST API provides an interface for applications to interact with a
WordPress site. These applications could be WordPress plugins, themes, or custom
applications that need to access WordPress site data.

One of the most well known implementations of the WP REST API is the Block Editor,
which is a JavaScript application that interacts with WordPress data through the
REST API.

## What does REST API mean

An API is an application programming interface. It’s a set of functions that allow
applications to interact with each other. WordPress has many different APIs, the
REST API is just one of them.

REST stands for [REpresentational State Transfer](https://en.wikipedia.org/wiki/Representational_state_transfer),
which is a software architectural style that describes a uniform interface between
physically separate components.

At it’s core, the WordPress REST API provides REST endpoints (URIs) which represent
the posts, pages, taxonomies, and other built-in WordPress data types. Your code
can send and receive data as JavaScript Object Notation (aka JSON) to these endpoints
to query, modify, and create content on your site.

Let’s dive into some concepts of REST to understand them better.

## Routes & Endpoints

In the context of the WordPress REST API, a route is a URI which can be mapped to
different HTTP methods.

An HTTP method is the type of request that’s made whenever you interact with anything
on the web. For example, when you browse to a URL on the web, a GET request is made
to the server to request the data.

When you submit a form, a POST request is made, which passes the submitted form 
data to the web server.

The mapping of an individual HTTP method to a route is known as an endpoint. Let’s
look at some examples of routes and endpoints.

If you open a browser, and go to the /wp-json/ URI of your local WordPress install,
you will be making a GET request to that URI.

The data returned is a JSON response showing what routes are available, and what
endpoints are available within each route.

By default, your browser will display the JSON data in its raw data format. To convert
it to a more readable format, you can use a browser extension like [JSON Formatter](https://chrome.google.com/webstore/detail/json-formatter/bcjindcccaagfpapjjmafapmmgkkhgoa)
for Chrome, [Basic JSON Formatter](https://addons.mozilla.org/en-US/firefox/addon/basic-json-formatter/)
for Firefox, or [JSON Peep](https://apps.apple.com/us/app/json-peep-for-safari/id1458969831?mt=12)
for Safari.

In this example /wp-json/ is a route, and when that route receives a GET request
it’s handled by the endpoint which displays the data. This data is what is known
as the index for the WordPress REST API.

By contrast, the /wp-json/wp/v2/posts route offers a GET endpoint which returns 
a list of posts, but also a POST endpoint. If you are an authenticated user, and
you submit the right data via a POST request to the /wp-json/wp/v2/posts route, 
that request is handled by the endpoint which creates new posts.

Typically, the same route (in this case /wp-json/wp/v2/posts) will have different
endpoints for different HTTP methods, including GET for fetching data, POST for 
creating data and DELETE for deleting data.

## Global Parameters

The WP REST API includes a number of global parameters which control how the API
handles the request/response handling. These operate at a layer above the actual
resources themselves, and are available on all resources.

Global parameters are implemented on REST API routes as query string parameters.
Query strings start with a ? and are followed by a series of key=value pairs, separated
by &.

Take a look at the /wp-json/wp/v2/posts route you looked at earlier, by requesting
the route in a browser, thereby activating the GET endpoint. As you can see, the
default is to return all available fields for a post.

However, if you update the route by adding the _fields global parameter, and then
specify the fields you want to return in the response as a comma delimited list.

    ```wp-block-code
    wp-json/wp/v2/posts?_fields=author,id,excerpt,title,link
    ```

If you make a second GET request, by refreshing the browser, only the fields you
have requested to be returned in the response are available.

## Pagination and Ordering

The WP REST API also supports pagination and ordering of results.

Pagination is handled by the per_page, page and offset parameters.

For example, you can update the wp-json/wp/v2/posts route to return only 5 posts
per page, by adding the per_page parameter to the route.

    ```wp-block-code
    wp-json/wp/v2/posts?_fields=author,id,excerpt,title,link&per_page=5
    ```

If you make a new GET request be refreshing the page, only the first 5 posts are
returned.

It’s also possible to order the results, using the order and order_by parameters.

For example, you can update the wp-json/wp/v2/posts route to order by post title,
in descending order.

    ```wp-block-code
    wp-json/wp/v2/posts?_fields=author,id,excerpt,title,link&per_page=5&orderby=title&order=asc
    ```

## Authentication

By default, the WP REST API uses the same cookie based Authentication method as 
logging into the WP dashboard. So for REST API endpoints that require a valid user,
if the authentication cookie is present, the request is authenticated.

However, it is also possible to application passwords, JSON Web Tokens, and OAuth
1.0a to authenticate requests. We will cover these authentication methods in a future
tutorial.

## Replacing admin-ajax with REST API endpoints

One of the biggest benefits of using the REST API in your plugins is that it can
replace your admin-ajax requests, using less code, and making your requests more
secure. To see this in action, let’s take a look at a simplified example.

In this example code, the plugin which adds a menu page to the WordPress dashboard.
The page has a button and a textarea, and when the button is clicked, an ajax request
is made to get the most recent posts, and display their titles in the textarea.

Besides the functionality to render the admin page, this is what the code looks 
like to implement Ajax. First, in the wp_learn_rest_enqueue_script function, you
need to use wp_localize_script to pass the ajax_url to the wp_learn_ajax object,
so that it’s available when the script is loaded.

Note that in this example, there’s no implementation of a nonce for security, but
it is recommended for a production plugin.

    ```php
    /**
     * Enqueue the main plugin JavaScript file
     */
    add_action( 'admin_enqueue_scripts', 'wp_learn_rest_enqueue_script' );
    function wp_learn_rest_enqueue_script() {
        wp_register_script(
            'wp-learn-rest-api',
            plugin_dir_url( __FILE__ ) . 'wp-learn-rest-api.js',
            array( 'jquery' ),
            time(),
            true
        );
        wp_enqueue_script( 'wp-learn-rest-api' );

        /**
         * Localize the script with the Ajax url to handle ajax requests
         */
        wp_localize_script(
            'wp-learn-rest-api',
            'wp_learn_ajax',
            array(
                'ajax_url' => admin_url( 'admin-ajax.php' ),
            )
        );
    }
    ```

Then, you’d need to the callback function to process the ajax request, by hooking
into a wp_ajax_ action hook

    ```php
    /**
     * Handles the learn_fetch_posts AJAX request.
     */
    add_action( 'wp_ajax_learn_fetch_posts', 'wp_learn_ajax_fetch_posts' );
    function wp_learn_ajax_fetch_posts() {
        $posts = get_posts();
        wp_send_json($posts);
        wp_die(); // All ajax handlers die when finished
    }
    ```

On the JavaScript side, some JavaScript would needed to handle the click event on
the button, and make the Ajax request. Typically this is usually handled using some
jQuery:

    ```javascript
    /**
     * JQuery to handle the Ajax request
     */
    jQuery( document ).ready(
        function ( $ ) {
            const loadPostsButton = $( '#wp-learn-ajax-button' );
            if ( loadPostsButton ) {
                loadPostsButton.on(
                    'click',
                    function ( event ) {
                        $.post(
                            wp_learn_ajax.ajax_url,
                            {
                                'action': 'learn_fetch_posts',
                            },
                            function ( posts ) {
                                const textarea = $( '#wp-learn-posts' );
                                posts.forEach( function ( post ) {
                                    textarea.append( post.post_title + '\n' )
                                } );
                            },
                        )
                    },
                );
            }
        },
    );
    ```

So what would this look like if you were using the WP REST API.

First of all, you don’t need to pass the ajax_url anywhere, so we can remove that
code from wp_learn_rest_enqueue_script. We also won’t be processing the ajax request,
so we can remove the wp_learn_ajax_fetch_posts function and associated hook. Finally,
we can remove the button, and add one to load the posts via the REST API

WordPress ships with a [Backbone JavaScript Client](https://developer.wordpress.org/rest-api/using-the-rest-api/backbone-javascript-client/)
for making direct requests to the WP REST API. This provides an interface for the
WP REST API by providing Backbone Models and Collections for all endpoints exposed
through the API.

To ensure that your code is able to use the Backbone.js client, you merely need 
to update your plugin’s dependency from `jquery` to `wp-api`.

This will ensure that your plugin’s JavaScript code is only loaded after the REST
API JavaScript client is loaded, so you can use it in your plugin.

In the JavaScript file, first you can delete the jQuery/Ajax related code.

Than you’ll want to start by registering a click event handler for the new button.

    ```javascript
    const loadPostsByRestButton = document.getElementById( 'wp-learn-rest-api-button' );
    if ( loadPostsByRestButton ) {
        loadPostsByRestButton.addEventListener( 'click', function () {
          // do something
        } );
    }
    ```

Then, in the event handler function, you can use the WP API client, by accessing
it from the global `wp` object, to create a new collection of posts

    ```javascript
    const allPosts = new wp.api.collections.Posts();
    ```

At this point, allPosts is simply an empty collection, so you will need to fetch
the posts, by calling the `fetch` method on the collection.

    ```javascript
       allPosts.fetch();
    ```

The fetch method returns a promise, so you can chain the `done` method to handle
the response, and implement a callback function which will accept the response from
the API request. You can specify a `posts` argument in this callback function, to
accept the response from the API request

    ```javascript
        const posts = allPosts.fetch().done(
            function ( posts ) {
                // do something with posts
            }
        );
    ```

Now you can simply loop through the `posts` object using `forEach` [method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach),
and access each post individually.

    ```javascript
        const posts = allPosts.fetch().done(
            function ( posts ) {
                posts.forEach( function ( post ) {
                  // do something with post
                } );
            }
        );
    ```

Finally, you can add the post title to the textarea. First you need to create an
instance of the textarea before the forEach loop, and then append the post title
to the textarea’s value property inside the forEach loop.

    ```javascript
        const posts = allPosts.fetch().done(
            function ( posts ) {
                const textarea = document.getElementById( 'wp-learn-posts' );
                posts.forEach( function ( post ) {
                  textarea.value += post.title.rendered + '\n'
                } );
            }
        );
    ```

Your final code will look something like this.

    ```javascript
    const loadPostsByRestButton = document.getElementById( 'wp-learn-rest-api-button' );
    if ( loadPostsByRestButton ) {
        loadPostsByRestButton.addEventListener( 'click', function () {
            const allPosts = new wp.api.collections.Posts();
            allPosts.fetch().done(
              function ( posts ) {
                const textarea = document.getElementById( 'wp-learn-posts' );
                posts.forEach( function ( post ) {
                  textarea.value += post.title.rendered + '\n'
                } );
            }
        );
        } );
    }
    ```

The great advantage of using the WP REST API and the Backbone.js JavaScript client,
is that you can use the same client over and over again. For example, if you wanted
to fetch users, you could simply create a new collection of users, and fetch them.
To do this via admin-ajax, you’d either need a new admin_ajax handler function, 
or update your existing function to accept a parameter to determine what to fetch.

The other advantage is that the API JavaScript client handles nonce checking for
you. With admin-ajax, you have to specify this yourself and check it in your handler
function. So using the REST API and the JavaScript client, your requests are more
secure.

This tutorial just scratches the surface of what is possible with the WP REST API.
To learn more about how it works, how to use it and how to extend it, check out 
the [WP REST API Handbook](https://developer.wordpress.org/rest-api/).

Happy coding

 [Practice on a private demo site](https://playground.wordpress.net/?networking=yes)

|  Length |  13 minutes |  
|  Language |  English |  
|  Subtitles |  English |

##  Suggestions

 Found a typo, grammar error or outdated screenshot? [Contact us](https://learn.wordpress.org/report-content-feedback/).

##  License

 [CC BY-SA 4.0 ](http://creativecommons.org/licenses/by-sa/4.0/)