When working with WordPress, REST API is one of the most powerful feature, whether building custom plugins, integrating external applications or simply extending the functionality of the site. This blog explores the internals how this works.

The Request Flow

The process begins as soon as a request is made to the WordPress site’s REST API endpoints.

A client(browser, app or server) makes a request to the server on the server’s REST URL.

parse_request action the WordPress core routing system kicks into action. The WP class processes the incoming request and the parse_request action is triggered. This is where WordPress begins to understand that the request is for the REST API and determines the correct route.

The rest_api_loaded() function is the entry point for the REST API, it checks if the request is for the REST API by checking the rest_route query variable. If a valid route is found it defines the REST_REQUEST constant which tells WordPress that it should proceed with processing it as a REST API request.

WordPress calls the rest_get_server() function which returns an instance of the WP_REST_Server class. This class handles the core tasks of routing, authentication and response generation. There is also a function which allows developers to replace the default server class with a custom implementation using the wp_rest_server_class filter.

Now, the rest_api_init action is triggered. This is one of the most important hooks in the REST API. It’s the perfect place to register custom routes with register_rest_route() or create custom REST fields using register_rest_field() or perform any other setup.

The WP_REST_Server’s serve_request() method is the main component of the REST API request processing. It is here WordPress checks the user’s authentication status, sets important HTTP headers (such as CORS) and applies various filters that enable developers to modify request processing.

A new WP_REST_Request object is created which holds all relevant details about the incoming request, such as HTTP method, query parameters, request body, headers, file uploads, etc.

The check_authentication() method ensures that the request is coming from a valid, authenticated source. This is where custom authentication mechanisms (like JWT tokens or API keys) can be applied. If authentication fails, the request is rejected with an appropriate error message.

Finally, the request is dispatched using the dispatch() method. This method matches the incoming request to one of the registered routes and executes the associated callback function. If the route doesn’t exist, a 404 error is returned.

The Response Flow

After WordPress has successfully matched the request to a route and executed the relevant callback it needs to handle the response.

The callback function responsible for handling the route is executed. This function processes the request accesses any necessary data, performs database queries and prepares the data to be returned in the response.

The respond_to_request() method is used to construct the final response. Before this method, several filters are applied to allow developers to modify the request or return a custom response.

If the route has a defined permission_callback, this function is executed to ensure the current user has the appropriate permissions to access the route. If the callback returns false or a WP_Error, the request is rejected with a suitable error message.

WordPress ensures that the response data is properly formatted as a WP_REST_Response object. This function is crucial because it handles potential errors and ensures the response is in a valid JSON format with the correct HTTP status code.

WordPress then checks for any filters like rest_post_dispatch, which can be used to adjust the final WP_REST_Response object before it’s sent to the client. You can modify the status code, add custom headers, or tweak the response data.

Headers such as Content-Type, Cache-Control, and any CORS-related headers are set. Also the appropriate HTTP status code is set.

The response data is then encoded into a JSON format using wp_json_encode(), and it’s sent to the client as the final output.

Finally, WordPress calls die() to terminate the execution, ensuring no further code is run after the response is sent.

Conclusion

Understanding the request-response flow in the WordPress REST API is essential for anyone looking to work with it at a deeper level. Whether building a plugin, developing custom functionality, having a solid grasp of this flow will make our development process smoother and more efficient.