Introducing the FacetWP REST API

FacetWP now includes a REST API endpoint.

What’s a REST API?

A REST API is a way to use programming code to access FacetWP’s raw data.

When would I need it?

Let’s say you’re building a custom application (e.g. React), but want to use WordPress’ database layer and FacetWP’s filtering. The REST API lets you talk directly to FacetWP, and have it send back raw data. Then you could use this data for things like building a custom filtering UI.

How do I use it?

By default, the FacetWP REST API is turned off. To enable it, use the following hook:

add_filter( 'facetwp_api_can_access', function( $boolean ) {
    return current_user_can( 'manage_options' );
});

Next, send a POST request to the following URL:

yoursite.com/wp-json/facetwp/v1/fetch

This endpoint accepts 1 parameter: data, which is a JSON encoded array. The defaults (before json_encode) look like the following:

$data = [
    'facets' => [],
    'query_args' => [
        'post_type' => 'post',
        'post_status' => 'publish',
        'posts_per_page' => 10,
        'paged' => 1,
    ],
    'settings' => [
        'first_load' => true
    ]
];

Full example

Let’s reproduce our Cars demo using the REST API. For simplicity, we’ll use wp_remote_post to make the API call, but this will vary depending on your framework.

$data = [
    'facets' => [
        'make' => [ 'audi' ],
        'vehicle_type' => []
    ),
    'query_args' => [
        'post_type' => 'cars',
        'posts_per_page' => 4
    ],
];

$url = 'https://yoursite.com/wp-json/facetwp/v1/fetch';

$response = wp_remote_post( $url, [
    'headers' => [
        'Authorization' => 'Basic ' . base64_encode( 'username:password' )
    ],
    'body' => [ 'data' => json_encode( $data ) ]
]);

In this example, we’re fetching cars and filtering by make = audi. We’ve also included vehicle_type and made it empty. This lets us fetch facet data for both facets, even though we’re only actually filtering by Make.

Response data

{
  "results":[
    1,
    2,
    3,
    4
  ],
  "facets":{
    "make":{
      "name":"make",
      "label":"Make",
      "type":"checkboxes",
      "selected":[
        "audi"
      ],
      "choices":[
        {
          "value":"audi",
          "label":"Audi",
          "depth":0,
          "count":20
        }
      ]
    },
    "vehicle_type":{
      "name":"vehicle_type",
      "label":"Vehicle Type",
      "type":"checkboxes",
      "selected":[

      ],
      "choices":[
        {
          "value":"car",
          "label":"Car",
          "depth":0,
          "count":17
        },
        {
          "value":"suv",
          "label":"SUV",
          "depth":0,
          "count":3
        },
        {
          "value":"minivan",
          "label":"Minivan",
          "depth":0,
          "count":0
        },
        {
          "value":"truck",
          "label":"Truck",
          "depth":0,
          "count":0
        },
        {
          "value":"van",
          "label":"Van",
          "depth":0,
          "count":0
        }
      ]
    }
  },
  "pager":{
    "page":1,
    "per_page":4,
    "total_rows":20,
    "total_pages":5
  }
}