Wordpress REST API - creating your first custom endpoint

#webdev #wordpress #php #programming

Wordpress provides access to a REST API which can be implemented to transform a Wordpress installation into a Headless CMS. Therefore the frontend can be created by using any framework like React or Angular while the data is stored into Wordpress and consumed by means of the built-in REST API.

You can also configure custom endpoints; in order words you can create your own API and include it into a Wordpress installation.

This short tutorial covers how to add a custom endpoint to the Wordpress REST API.

Creating a new plugin and activating it

In order to create a custom API endpoint a new plugin must be created and activated so head over to the Plugins folder and add the folder called restPlugin inside; then create the file **restplugin.php **and add the next php code snippet:

<?php
/* 
Plugin Name: Rest Plugin
Description: This plugins generates a testing API
Author: YOUR-NAME
*/

The previous comment provides metadata regarding the plugin and it's used to indicate Wordpress that this folder is a plugin; also the metadata is shown within the Plugins screen.

Then head over to the Dashboard and inside the Plugins screen look for the plugin and activate it.

Adding a new file to the project

Add a new php file called register.php; this is the file where the php code will be added later on but before that it must be included into the project so open the file restplugin.php and add the next line below the :

require_once WP_PLUGIN_DIR."/restPlugin/register.php";

Creating the API endpoint

Open the register.php file and add the next code snippet inside:

<?php


function rch_handle_welcome_message(){

    return rest_ensure_response("Welcome to the restplugin API");
}


function rch_register_api_routes(){


    register_rest_route(
        "restplugin/v1",
        "/welcome-message",
       array(
        "methods" => "GET",
        "callback" => "rch_handle_welcome_message"
       )
    );
}


add_action("rest_api_init","rch_register_api_routes");

The rest_api_init hook is used to configure the REST API. The register_rest_route() function is called to add the new endpoint to the API.

The first parameter passed in to the function is called the namespace and it's like a prefix used to classify the endpoints or group the endpoints into a category. The namespace is very important because it prevents the endpoints from crashing with other endpoints from another plugin.

The second parameter is the path to the API resource; paths must also be unique within the same namespace to avoid collisions with other paths for other API resources.

The combination of the namespace and the path forms the route; later on it will be shown how to implement the route to access a given API resource.

The third parameter is an array which describes the HTTP methods allowed for the newly added API endpoint; in this case the GET method only. The function which handles the HTTP request for a given route and HTTP method is known as the endpoint and is indicated into the array as well.

Note that some people define an endpoint as the specific address for a given API resource which includes the HTTP method and the route.