Creating a Custom REST API

The WordPress REST API can be used to perform basic searches. We cannot perform advanced searches that are aware of relationships between post types. For example, if we search for literature, we get only one result back which is the course post for Literature course. The query wp-json/wp/v2/event?search=literature will return an empty array instead of the two events (Reading Group and Writers Recognition Night) which are related to the literature course. The native search logic of the WordPress REST API searches between obvious fields like title and main body content. It does not search within custom fields and does not know how to interpret the relationships that we set up between different post types.

In order to handle post type relationships efficiently, it becomes necessary to implement a customized REST API that is capable of recognizing and working with these relationships.

Advantages of custom REST API

Building a custom REST API has a number of advantages which are listed below:

1. The custom REST API will be aware of relationships between post types as the built-in search logic does not cater to our needs.

2. It can make the search faster as we can control how much data to send. The native REST API sends a lot of data while we only need a title, permalink and a few other properties. Sending less data makes the search faster.

3. We can return back everything in one URL instead of having to send out a number of asynchronous requests to different URLs. The native REST API has one URL per post type.

Creating a custom route

The custom REST API will be available at a URL that is different from the WordPress REST API URL. The WordPress REST API can be accessed at wp-json/wp/v2/. In this URL:

• wp-json is the root of the rest API.

• wp is the namespace which tells that the URL belongs to the core WordPress REST API. Our custom route will have a different namespace.

• v2 represents version 2, with the version number being an integral part of the namespace. Incorporating a version number into your API is highly recommended as it allows for smooth transitions and updates. By modifying the version number, you ensure compatibility for both the previous and updated URLs, enabling users of your API to adapt to any changes you make while maintaining usability.

When creating a custom route, we will use the same root wp-json but a different namespace. We will create a new REST API at a different URL accessible at wp-json/excellence/v1/search.

The code for creating a custom route can be written in the functions.php file. However, for the sake of readability, we will write it in a separate file and include the file in functions.php.

In the theme folder, create a new folder called inc. This folder will contain all the files that are needed by other PHP files in our theme. From the Creating a Custom Theme lesson, recall that this folder is part of the theme hierarchy.

Inside the inc folder, create a new file named search-route.php. This file will contain PHP code so we will begin the file with the <?php opening PHP tag. Create a function school_rest_api This function will be called at the rest_api_init hook which fires when preparing to serve a REST API request. It creates endpoints listed in the callback function.