September 04, 2022

Create REST API in WordPress (With Examples)

WordPress empowers millions of websites globally and it becomes powerful headless CMS when the WordPress REST API is utilized. Learn in this post to create a WordPress API with example code.

REST API in WordPress

A WordPress REST API is set of endpoints which allows developers to interact with website data through HTTP requests. It is structured and JSON based interface to retrieve, create, update and delete website data in a flexible way. In this post we will learn how to access WordPress API endpoints and how to create custom endpoints with examples.

 

How to Access WordPress API Endpoints

The REST API in WordPress is enabled by default since the version 4.7 and later. The endpoints of REST API can be accessed by appending /wp-json/ to website URL to fetch website details, while for other endpoints like posts, pages and users it can be accessed by appending /wp-json/wp/v2/ to the URL. The following are WordPress API endpoints available by default:

  • /posts: To get, create, update and delete posts.
  • /pages: To get, create, update and delete pages.
  • /categories: To get, create, update and delete categories.
  • /tags: To get, create, update and delete tags.
  • /comments: To get, create, update and delete comments.
  • /users: To get, create, update and delete users.

For sake of example we will be using posts endpoints. So to get posts we will use the endpoint with GET request like this:

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

To create a post we will need to send a POST request to posts endpoints with authentication headers like this:

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

// Headers
Authorization: Basic base64encoded(username:password)
Content-Type: application/json

// Body
{
  "title": "My New Post",
  "content": "This is the content of the new post.",
  "status": "publish"
}

To update a post we will send a POST request to posts endpoint with authentication headers like in create post example:

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

// Headers
Authorization: Basic base64encoded(username:password)
Content-Type: application/json

// Body
{
  "title": "Update post title",
}

To delete a post we will send a DELETE request to posts endpoint with authentication headers. The query parameter ?force=true can be used to force post to delete instead of moving to trash like this: 

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

// Headers
Authorization: Basic base64encoded(username:password)

These were the four basic example of how to use built-in REST API endpoints in WordPress.

 

How to Register Custom REST API Endpoints in WordPress

In addition to default REST endpoints available in WordPress, It allows developers to create their own custom REST API endpoints making it flexible for developers to manage website data efficiently via headless API requests. Following are the steps to register a custom REST API endpoint in WordPress with some PHP code:

  • Add an action for rest_api_init providing the function to register API endpoints.
  • Inside the function use the WordPress function register_rest_route() with three parameters. The first one is the endpoint prefix, second one is the specific API endpoint and third one is an array of arguments.
  • Add the request methods allowed for this specific endpoint.
  • Add the callback function to process API request and return response.
  • Add the permission check callback function if the endpoint requires permission check.
// Action hook to register custom REST API endpoints
add_action('rest_api_init', 'custom_rest_routes');
function custom_rest_routes(): void
{
    register_rest_route('custom-endpoint/v1', '/custom-posts/', [
        'methods' => WP_REST_Server::ALLMETHODS,
        'callback' => 'custom_posts_rest_callback',
        'permission_callback' => 'custom_posts_rest_permissions_callback',
    ]);
}

// Callback function to process API request and return response
function custom_posts_rest_callback(WP_REST_Request $request)
{
    // The code logic goes here
}

// Check the permissions here
function custom_posts_rest_permissions_callback()
{
    return current_user_can('manage_options');
}

This is a general example of registering any API endpoint in WordPress. We hook into rest_api_init hook and register REST routes using register_rest_route() function with a callback function to process the request and return the response and a permission callback function. The above code snippet can register a specific REST route for all HTTP methods, however we can handle different HTTP methods differently. All these methods should then return WP JSON response.

 

GET API Request in WordPress (GET Method)

The GET method is used to fetch a data or set of data from server. It only retrieves data not modify it, like retrieving all posts or retrieving a single post providing the post ID as parameter. The WP REST route for GET method can be registered like this:

// Get all posts or single post API endpoint
register_rest_route('custom-endpoint/v1', '/custom-posts/', [
    [
        'methods'  => WP_REST_Server::READABLE, // GET
        'callback' => 'get_custom_posts',
        'permission_callback' => 'custom_posts_rest_permissions_callback',
    ]
]);

// Callback function to process request and return response
function get_custom_posts(WP_REST_Request $request): WP_REST_Response
{
    $posts = get_posts([
        'post_type'      => 'post',
        'posts_per_page' => 5,
        'post_status'    => 'publish',
    ]);

    $data = [];

    foreach ($posts as $post) {
        $data[] = [
            'id'      => $post->ID,
            'title'   => get_the_title($post->ID),
            'content' => apply_filters('the_content', $post->post_content),
            'date'    => $post->post_date,
        ];
    }

    return new WP_REST_Response($data, 200);
}

// Get specific post by ID API endpoint
register_rest_route('custom-endpoint/v1', '/custom-posts/(?P<id>\d+)', [
    [
        'methods'  => WP_REST_Server::READABLE, // GET
        'callback' => 'get_custom_post',
        'permission_callback' => 'custom_posts_rest_permissions_callback',
    ]
]);

// Callback function to process request and return response
function get_custom_post(WP_REST_Request $request): WP_REST_Response
{
    $post_id = (int) $request['id'];
    
    $post = get_post($post_id);

    if (!$post) {
        return new WP_REST_Response([
            'message' => __('Failed to get post', 'text-domain')
        ], 400);
    }

    return new WP_REST_Response($post, 200);
}
 

Create API Request in WordPress (POST Method)

The POST method is used to create a new resource on server where the data is sent in request body. The WP REST route for POST method to create a resource can be registered liked this:

// Create a post API endpoint
register_rest_route('custom-endpoint/v1', '/custom-posts/', [
    [
        'methods'  => WP_REST_Server::CREATABLE, // POST
        'callback' => 'custom_create_post',
        'permission_callback' => 'custom_posts_rest_permissions_callback',
    ],
]);

// Callback function to create a post and return response
function create_custom_post(WP_REST_Request $request): WP_REST_Response
{
    $title   = sanitize_text_field($request->get_param('title'));
    $content = wp_kses_post($request->get_param('content'));

    $post_id = wp_insert_post([
        'post_title'   => $title,
        'post_content' => $content,
        'post_status'  => 'publish',
        'post_type'    => 'post',
    ]);

    if (is_wp_error($post_id)) {
        return new WP_REST_Response([
            'message' => __('Failed to create post', 'text-domain')
        ], 400);
    }

    return new WP_REST_Response([
        'message' => __('Post created successfully', 'text-domain'),
        'post_id' => $post_id
    ], 201);
}
 

Update API Request in WordPress (POST Method)

The update request uses the same POST method with one difference that it accepts the ID of resource to update it. This does not create a new resource and WP REST route for POST method to update a resource can be registered like this:

// Update a post API endpoint
register_rest_route('custom-endpoint/v1', '/custom-posts/(?P<id>\d+)', [
    [
        'methods'  => WP_REST_Server::EDITABLE, // POST (Update)
        'callback' => 'update_custom_post',
        'permission_callback' => 'custom_posts_rest_permissions_callback',
    ]
]);

// Callback function to update a post and return response 
function update_custom_post(WP_REST_Request $request): WP_REST_Response
{
    $post_id = (int) $request['id'];

    $title   = sanitize_text_field($request->get_param('title'));
    $content = wp_kses_post($request->get_param('content'));

    $updated = wp_update_post([
        'ID'           => $post_id,
        'post_title'   => $title,
        'post_content' => $content,
    ], true);

    if (is_wp_error($updated)) {
        return new WP_REST_Response([
            'message' => __('Failed to update post', 'text-domain')
        ], 400);
    }

    return new WP_REST_Response([
        'message' => __('Post updated successfully', 'text-domain'),
        'post_id' => $post_id
    ], 200);
}
 

Delete API Request in WordPress (DELETE Method)

The DELETE method is used to delete a resource on server where it expects an ID of resource to uniquely identify it and delete it. The WP REST route for DELETE method can be registered like this:

// Delete a post by id API endpoint
register_rest_route('custom-endpoint/v1', '/custom-posts/(?P<id>\d+)', [
    [
        'methods'  => WP_REST_Server::DELETABLE, // DELETE
        'callback' => 'delete_custom_post',
        'permission_callback' => 'custom_posts_rest_permissions_callback',
    ],
]);

// Callback function to delete a post and return response
function delete_custom_post(WP_REST_Request $request): WP_REST_Response
{
    $post_id = (int) $request['id'];

    $deleted = wp_delete_post($post_id, true); // true = force delete

    if (!$deleted) {
        return new WP_REST_Response([
            'message' => __('Failed to delete post', 'text-domain')
        ], 400);
    }

    return new WP_REST_Response([
        'message' => __('Post deleted successfully', 'text-domain'),
        'post_id' => $post_id
    ], 200);
}

We just demonstrated how to create custom REST API in WordPress which can be accessed at https://example.com/wp-json/custom-endpoint/v1/custom-posts with methods to get, add, update and delete posts via API. This feature of WordPress REST API makes it a power tool and transforms it from just a CMS to flexible platform through API endpoints. Always remember to add authentication to secure API calls when data is supposed to change and always sanitize user input for security.

Home