REST API Routes

IntroductionIntroduction

WP Grid Builder offers 2 custom REST API routes for developers in order to manipulate facets and content on the frontend. These REST API routes allow to fetch facets settings and choices or to search for specific facet choices.

PermissionPermission

By default, the REST API routes are disabled because the permission callback return false. To enable the REST API routes and/or to set specific permission(s), you need to use the following PHP filter:

PHP
functions.php
add_filter(
	'wp_grid_builder/rest_api/permission',
	function( $allowed, $request ) {
		return true;
	},
	10,
	2
);

Permission will depend of the context of your application.

Fetch RouteFetch Route

The fetch route allows to get facets data according to query arguments and facet parameters. This POST route accepts as body content a JSON string. Here you will find the following arguments that need to be stringlified in the body of the request:

ArgumentTypeDescription
langstringQueried language (optional)
facetsobjectHolds filter facets to retrieve
source_typestringObject type to query (post_type, term, user)
query_argsobjectHolds query arguments

You can fetch route content with JavaScript, for example, as follows:

JS
JS Fetch Route
fetch(
	'//example.com/wp-json/wpgb/v1/fetch',
	{
		method: 'POST',
		headers: {
			'Content-Type': 'application/json'
		},
		body: JSON.stringify(
			{
				facets: {
					facet_slug_1: [ 'value_1', 'value_2' ],
					facet_slug_2: [ 'value_1' ],
					facet_slug_3: [],
					facet_slug_4: [],
				},
				source_type: 'post_type',
				query_args: {
					post_type: 'post',
					posts_per_page: 10,
				},
			}
		),
	}
)
.then( response => response.json() )
.then( response => console.log( response ) );

This request will return the following response data:

JS
JS Response
{
	facets: { // Object of facets (index-based by facet ids).
		1: {
			name: 'Categories',
			slug: 'facet_slug_1',
			type: 'checkbox',
			selected: [ 'value_1', 'value_2' ],
			choices: [
				{
					name: 'Value 1',
					value: 'value_1',
					parent_id: 0,
					term_id: 1,
					count: 10,
				},
				{
					name: 'Value 2',
					value: 'value_2',
					parent_id: 0,
					term_id: 2,
					count: 8,
				},
				{…},
				{…},
				{…},
			],
			settings: {
				hierarchical: 0,
				show_less_label: '- Show less',
				show_more_label: '+ Show more',
			},
		},
		2: {…},
		3: {…},
		4: {…},
	},
	results: [ // Array of raw post data.
		{…},
		{…},
		{…},
		{…},
		{…},
		{…},
		{…},
		{…},
		{…},
		{…},
	],
	total: 3000 // Total amount of posts found.
}

Search RouteSearch Route

The search route is pretty similar to the fetch route excepted that it allows to search for choices from a facet slug. It is pretty handy to create autocomplete list or asynchrounous combobox for example. Here you will find the following arguments that need to be stringlified in the body of the request:

ArgumentTypeDescription
langstringQueried language (optional)
facetsobjectHolds filter facets used to filter content
source_typestringObject type to query (post_type, term, user)
query_argsobjectHolds query arguments
searchobjectHolds facet slug to search in and searched string

You can search for facet choices with JavaScript, for example, as follows:

JS
JS Search Route
fetch(
	'//example.com/wp-json/wpgb/v1/search', {
  	method: 'POST',
	headers: {
        'Content-Type': 'application/json'
    },
  	body: JSON.stringify(
		{
			facets: {
				facet_slug_1: [ 'value_1', 'value_2' ],
				facet_slug_2: [ 'value_1' ],
			},
			source_type: 'post_type',
			query_args: {
				post_type: 'post',
				posts_per_page: 10,
			}
			search: {
				facet: 'facet_slug_3',
				string: 'shirt',
			},
		}
	),
} )
.then( response => response.json() )
.then( response => console.log( response ) );

This request will output an array of facet choices from the searched facet:

JS
JS Response
[
	{
		name: 'Overshirt',
		value: 'overshirt',
		parent_id: 0,
		term_id: 3,
		count: 34,
	},
	{
		name: 'Flannel Shirt',
		value: 'flannel-shirt',
		parent_id: 0,
		term_id: 8,
		count: 12,
	},
	{…},
	{…},
	{…},
]

PHP HooksPHP Hooks

The REST API routes include PHP action and filters in order to easily manipulate requests and format responses. Please find below the links to the PHP documentation: