Using Better Rest Endpoints To Slim Down WP Rest API Responses

WordPress has always been a powerful tool for developers and content creators to deliver their story. With an intuitive backend for posts, pages, and just about everything else, it makes it easy to deliver your message, grow your brand, or sell your product. When the WordPress Rest API was introduced into WordPress core, the possibilities grew by leaps and bounds. One of the possibilities that opened up after this addition was the ability to run WordPress as a headless CMS and build the front end of your site with React or any other framework you’d prefer.

One of the downsides to core WordPress Rest API is the sheer amount of data it returns. Let’s take a look at a typical response of a collection of pages from a dummy site I spun up.

A standard WordPress Rest API response. (Content has been collapsed to take up less space, and even then it all still doesn’t fit in my screenshot!)

As you can see, we get a lot of great data, but a lot of this data (such as comment_status, _links, ping_status, or even the multiple modified fields) clutters up our response and can add unnecessary bloat and load times, especially when our sites start to grow in size. A lot of times, we may just want a list of page titles with very little information returned or posts with only excerpts displayed for an index view…

Enter Better Rest Endpoints

At factor1 we’ve been diving deeper into building sites with a React front end and a headless WordPress back end. It was clear that when building these sites we wanted more flexibility in how our data was returned and a few nice additions to make building these types of sites easier, thus Better Rest Endpoints was born. Our objectives were simple:

• Slim down collection (posts, pages, etc) data
• Include Advanced Custom Field values (but don’t worry — haven’t installed or don’t use ACF? The plugin is smart enough to just keep on keepin’ on without it)
• Add a menu endpoint to easily integrate WordPress Menus to the front end
• Give the developer flexibility to return just the data that they want

So let’s take a look at getting a collection of pages using Better Rest Endpoints.

Note: it may be useful to take a look at the documentation while following along.

Getting Pages

If you’re following along with the documentation, you’ll see that the endpoint for pages is better-rest-endpoints/v1/pages. Without any query parameters passed through the endpoint, you will receive a collection pages with the following:

• ID
• Slug
• Template Name
• Title
• Content
• ACF Fields
• All possible featured media thumbnail sizes & urls

A typical pages response from Better Rest Endpoints (only one page shown for the sake of image size 😉)

Depending on your use case, all the data may be great, but let’s say that we are just going to be building our routes for our app or some sort of index view for our users. We probably won’t need content, ACF, or featured media, so we can slim this down even more using query parameters. Building this response is easy:

better-rest-endpoints/v1/pages?content=false&acf=false&media=false

As you can see — we are telling Better Rest Endpoints to omit the content, ACF, and media (featured media) from our response and it comes back looking like this:

Look at how clean and lean!

This response looks much cleaner and also slims down our kilobytes a bit (Hey, anything counts!). Our original response weighed in at 79.49 KB and without content, ACF, and media it comes in at 1.89 KB. That’s a pretty damn good reduction in size, eh? If you build themes that rely on ACF heavily or have many thumbnail sizes on your site, that initial response size could be even higher, and to be honest, our dummy site content is pretty slim with almost no ACF fields even used.

The pages endpoint has even more parameters you can use; as per the documentation, the full list is:

• exclude (integer | exclude a page by ID from returning in the response)
• orderby (string | the same as orderby in a WP_Query)
• order (string | 'ASC' vs 'DESC')
• per_page (int | how many pages to return in the collect, defaults to the WordPress default)
• page (int | what page in the collection to view)
• content (boolean | set to false to hide content)
• acf (boolean | set to false to hide acf object)
• media (boolean | set to false to hide media object AKA featured media)

Using these parameters, a developer can really take full advantage of the WordPress Rest API and get the exact data they need, without wasting precious loading times on unused data. So now that we have getting a collection of pages out of the way, let’s take a look at getting a single page.

Getting A Single Page

Getting a single page is even simpler than getting a collection of pages. All we need to do is hit the Better Rest Endpoint API for the page — let’s pretend we want a page with the ID of 58:

better-rest-endpoints/v1/page/58

A typical single page request from Better Rest Endpoints

Since we’re getting a single page, we are returned all the relevant data you’d want for a single page:

• ID
• Slug
• Title
• Template Name
• Content
• All Possible featured media thumbnail sizes & URLs
• ACF fields, if applicable

Note: As of writing this article (version 1.2.0) single pages and posts do not accept any other arguments. This could change in the future if the use case arises.

Other Neat Features

Menus

One big thing that was lacking from the core WordPress Rest API was an easy way to get WordPress Menus. We take pride in how easy it is to edit our sites we create for clients, so allowing the menus to be controlled by WordPress was a must. Let’s pretend we created a menu called “Primary”; we can access it using the menu’s slug of primary. Let’s take a look at the endpoint and its response:

better-rest-endpoints/v1/menus/primary

A typical menu response from Better Rest Endpoints

Now we have a nice and neat response for each item that we can use to build out our front end menus.

Wrapping It All Up

Better Rest Endpoints has been in development since September 2017 and was just recently released to the WordPress.org Plugin Repository. We are really proud and excited for what we can build with it and the advantages it gives us. We really hope it can help you as well. Of course, this is a free open-source plugin that gives us a chance to give back to the community that has given us so much.

Keep in mind Better Rest Endpoints is not just limited to pages… it also works on Posts, Custom Post Types, Taxonomies, and Search. Take a look at the full documentation to see what else you can do with it.

If you find a bug or have questions, don’t hesitate to open an issue on GitHub, a support ticket on WordPress.org or even send a tweet my way and I’ll happily help out. Until next time! 🎉🍻