factor1/better-rest-endpoints

A WordPress plugin that serves up slimmer WP Rest API endpoints.

better-rest-endpoints

A WordPress plugin that serves up slimmer WP Rest API endpoints.

Endpoints

Posts

better-rest-endpoints/v1/posts Gets a collection of posts. Accepts the following parameters:

• acf (boolean - setting to false omits acf from being returned)
• author (string) limit posts by author nice name (user_nicename)
• category id (int)
• category_name (string)
• exclude_categories (string) comma-separated array of category IDs
• content (boolean) set to false to omit content from showing in JSON response
• exclude (int) a post ID to exclude from the response
• media (boolean - setting to false omits media (featured media) from being returned)
• order (string - 'ASC' vs 'DESC')
• orderby (string)
• page (int)
• per_page (int)
• tag id (int)
• exclude_tags (string) comma-separated array of tag IDs
• yoast (boolean - setting to false omits yoast from being returned)

It returns a JSON response with the following:

• ACF fields, if applicable
• all possible thumbnail sizes & URL
• Author, user_nicename, & Author ID
• Categories
• Category IDs
• content
• date (ISO 8601)
• excerpt
• id
• slug
• Tag IDs
• Tags
• title
• Yoast SEO fields, if applicable

Post

better-rest-endpoints/v1/post/{id} Get a post by ID.

Accepts the following parameters:

• ID (int)

Returns a JSON response with the following:

• ACF fields, if applicable
• all possible thumbnail sizes & URLs
• Author, user_nicename, & Author ID
• Categories
• Category IDs
• content
• date (ISO 8601)
• excerpt
• id
• slug
• Tag IDs
• Tags
• title
• Yoast SEO fields, if applicable

Post by slug

better-rest-endpoints/v1/post/{slug} Get a post by ID.

Accepts the following parameters:

• slug (string)

Returns a JSON response with the following:

• ACF fields, if applicable
• all possible thumbnail sizes & URLs
• Author, user_nicename, & Author ID
• Categories
• Category IDs
• content
• date (ISO 8601)
• excerpt
• id
• slug
• Tag IDs
• Tags
• title
• Yoast SEO fields, if applicable

Pages

better-rest-endpoints/v1/pages Gets a collection of pages. Accepts the following parameters:

• acf (boolean - setting to false omits acf from being returned)
• content (boolean - setting to false hides the content from the response)
• exclude (int)
• exclude (int) a post ID to exclude from the response
• media (boolean - setting to false omits media (featured media) from being returned)
• order (string - 'ASC' vs 'DESC')
• orderby (string)
• page (int)
• per_page (int)
• yoast (boolean - setting to false omits yoast from being returned)

Returns the following JSON Response:

• ACF Fields
• all possible thumbnail sizes & URLs
• Content
• ID
• Slug
• Template Name
• Title
• Yoast SEO Fields

Page by ID

better-rest-endpoints/v1/page/{id} Get a page by ID.

Accepts the following parameters:

• ID (int)

Returns a JSON response with the following:

• ACF fields, if applicable
• all possible thumbnail sizes & URLs
• content
• id
• slug
• template name
• title
• Yoast SEO fields, if applicable

Post by slug

better-rest-endpoints/v1/page/{slug|path} Get a page by slug or path. Requesting a page by slug will only return a page with no parent with the requested slug. If multiple pages have the same slug the page needs to be requested by passing the entire path. eg. better-rest-endpoints/v1/page/technology/about or better-rest-endpoints/v1/page/services/about instead of just better-rest-endpoints/v1/page/about

Accepts the following parameters:

• slug, path (string)

Returns a JSON response with the following:

• ACF fields, if applicable
• all possible thumbnail sizes & URLs
• Author, user_nicename, & Author ID
• Categories
• Category IDs
• content
• date (ISO 8601)
• excerpt
• id
• slug
• Tag IDs
• Tags
• title
• Yoast SEO fields, if applicable

Custom Post Type Collection

better-rest-endpoints/v1/{custom_post_type} Gets a collection of posts from a custom post type. Accepts the following parameters:

• acf (boolean - setting to false omits acf from being returned)
• content (boolean - setting to false omits the_content from being returned)
• exclude (int) a post ID to exclude from the response
• media (boolean - setting to false omits media (featured media) from being returned)
• orderby (string) - see the codex for options, currently does not support multiple values
• page (int)
• per_page (int)
• yoast (boolean - setting to false omits yoast from being returned)

Returns the following JSON response:

• ACF fields if applicable
• all possible thumbnail sizes & URLs
• Author, user_nicename, & Author ID
• content
• date (ISO 8601)
• excerpt
• ID
• post terms
• slug
• title
• Yoast SEO fields if applicable

Custom Post Type Post by ID

better-rest-endpoints/v1/{custom_post_type}/{id} Gets a single custom post type item. Accepts the following parameters:

• ID

Returns the following JSON Response:

• ACF Fields, if applicable
• all possible thumbnail sizes & URLs
• Author, user_nicename, & Author ID
• content
• date (ISO 8601)
• excerpt
• ID
• post terms
• slug
• title
• Yoast SEO Fields, if applicable

Custom Post Type Post by Slug

better-rest-endpoints/v1/{custom_post_type}/{slug} Gets a single custom post type item. Accepts the following parameters:

• slug

Returns the following JSON Response:

• ACF Fields, if applicable
• all possible thumbnail sizes & URLs
• Author, user_nicename, & Author ID
• content
• date (ISO 8601)
• excerpt
• ID
• post terms
• slug
• title
• Yoast SEO Fields, if applicable

Get Posts Belonging To A Taxonomy Term

better-rest-endpoints/v1/{taxonomy}/{term} Gets posts from a taxonomy term. Accepts the following parameters:

• acf (boolean - setting to false omits acf from being returned)
• content (boolean - setting to false omits the_content from being returned)
• exclude (int) a post ID to exclude from the response
• media (boolean - setting to false omits media (featured media) from being returned)
• orderby (string) - see the codex for options, currently does not support multiple values
• page (int)
• per_page (int)
• yoast (boolean - setting to false omits yoast from being returned)

Returns the following JSON Response:

• ACF Fields, if applicable
• all possible thumbnail sizes & URLs
• Author, user_nicename, & Author ID
• content
• date (ISO 8601)
• excerpt
• ID
• post terms
• slug
• title
• Yoast SEO Fields, if applicable

Menus from slug (name)

better-rest-endpoints/v1/menus/{menu-slug} Gets a WordPress Menu by slug. Accepts no parameters.

Returns the following JSON Response in each item object:

• classes (array)
• description
• ID
• menu item parent
• menu_order
• slug
• target
• title
• url

Menus from location (theme location)

better-rest-endpoints/v1/menus/{menu-slug} Gets a WordPress Menu by the theme location. Accepts no parameters.

Returns an empty array if the location can not be found or if it has no assigned menu. Returns an array of the following objects if a menu is assigned to the specified location:

• classes (array)
• description
• ID
• menu item parent
• menu_order
• slug
• target
• title
• url

Taxonomies

better-rest-endpoints/v1/taxonomies Gets a list of taxonomies used by WordPress. Accepts no parameters.

Returns the following JSON response in each item object:

• Description
• Hierarchical (true/false)
• Name
• Slug

Search

better-rest-endpoints/v1/search Gets a collection of posts and pages based on the search parameter. Accepts the following parameters:

• acf (boolean - setting to false omits acf from being returned)
• category id (int)
• content (boolean) set to false to omit content from showing in JSON response
• media (boolean - setting to false omits media (featured media) from being returned)
• page (int)
• per_page (int)
• search (string | required)
• tag id (int)
• exclude_tags (string) comma-separated array of tag IDs
• exclude_categories (string) comma-separated array of category IDs
• yoast (boolean - setting to false omits yoast from being returned)

It returns a JSON response with the following (returns an empty array if no posts found):

• ACF fields, if applicable
• all possible thumbnail sizes & URL
• Author, user_nicename, & Author ID
• Categories
• Category IDs
• content
• date (ISO 8601)
• excerpt
• id
• slug
• Tag IDs
• Tags
• title
• Yoast SEO fields, if applicable

ACF Options

better-rest-endpoints/v1/options/acf Gets an array of all ACF Options Page fields, returns an empty array if none are found or if ACF is not active.

better-rest-endpoints/v1/options/acf/{field} Gets a single ACF Options Page field, returns null if ACF is not active or the field does not exist.

Accepts the following parameters:

• field (string - can be either the field key or the field name)

Hooks and Filters

Filter the Custom Post Types endpoints

add_filter('better_rest_endpoints_cpt_collection', function($cpt_collection){
	$cpt_collection = array_flip($cpt_collection);
	unset($cpt_collection['oembed_cache']);
	unset($cpt_collection['_pods_template']);
	unset($cpt_collection['_pods_pod']);
	unset($cpt_collection['_pods_field']);
	$cpt_collection = array_values( array_flip($cpt_collection) );
	return $cpt_collection;
});

better-rest-endpoints's Issues

Update readme for menus/location endpoint

Hi there,

Just a small suggestion for your readme.md documentation. The endpoint below "Menus from location (theme location)" seems to be incorrect. It should be:

better-rest-endpoints/v1/menus/location/{menu-slug}

Thanks for this nice plugin :)

Combine fields with WPML REST API

Hey guys,

Thanks for better-rest-endpoints! I like it a lot, however I have multilanguage project and I need to include WPML translations in api response. This sort of inclusion exists for wordress /wp/ - https://github.com/shawnhooper/wpml-rest-api/blob/master/wpml-rest-api.php

Could, you please, help me combine it with yours get_post_by_slug.php? How do I add 'wpml_translations' field that implemented in the example above to your post object?

Exclude post by id

Need to be able to exclude a post by id.

WooCommerce support?

First, this plugin is totally incredible and is already making things much easier.

Having a look at all the endpoints, there are some for products. Does this support WooCommerce out of the box? There wasn't anything in the docs about WC.

All I can say is thanks...this is like the coolest thing ever. I can't believe more people aren't using it.

Content parameter not working

Adding the content=false parameter does not work correctly after fixing the callback validation functions.

Caching support?

Not really a pressing issue but a question: has anyone gotten BRE working with either WP Rest Cache or Rest API Cache?

After trying both of those out, they do not seem to like the menu endpoint from BRE at all, so much so that I have had to disable them.

I have some front end javascript caching working with Local/Session Storage in a headless WP app but some server-side caching that works with BRE for specific endpoints would be great to help with initial page loads.

Custom post type by taxonomy

I see that you can query posts by category with /wp-json/better-rest-endpoints/v1/post?category=43. But it does not seem to work for custom post type.

I know wp-json/wp/v2/products?categories=43 works but then you don't have the benefit of the nicely formatted response by your plugin.

Maybe

category id (int)
category_name (string)

needs to be enabled?

Parent Relationships in Page Endpoints

Adding parent relationships to the Pages endpoint is needed for proper routing in some cases.

error 500 using polylang

Hi,
I have an issue with your plugin.

I set a custom post type "dishes" and a custom taxonomy "tax_menu" with two terms "gavitella" and "light-snacks". What I want is to create Menus and associate dishes to them.

If I use the route example "better-rest-endpoints/v1/{taxonomy}/{term}", which in my case is HOME/wp-json/better-rest-endpoints/v1/tax_menu/light-snacks I get an error 500.

I use polylang to manage translations and I found that disabling it solves the issue but I can not understand why. I know that polylang uses taxonomy and terms to assign langs to posts, could it be the problem?
What do you suggest? Thank you.

Activation Issue w/ WP_DEBUG on

Via a user on slack, w/ possible solution:

just change public function instance() { to public static function instance() { on line 57 of the main plugin file

Missing guten blocks from the pages endpoint

The guten blocks content is not included. Is there some way to register a custom field into an endpoint ?

Here is a link on how to add parsed guten blocks into the rest api, if you are thinking about adding it: https://wpscholar.com/blog/add-gutenberg-blocks-to-wp-rest-api/

Endpoints Failing without ACF Pro

Endpoints are broken when ACF Pro is not installed. ACF Free also fails.

Stack trace from php7 user:

[19-Jan-2018 19:27:15 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function is_plugin_active() in /Users/alexanderpersky/Sites/wordpress/wp-content/plugins/better-rest-endpoints/includes/get_acf.php:12
Stack trace:
#0 /Users/alexanderpersky/Sites/wordpress/wp-content/plugins/better-rest-endpoints/includes/get_posts.php(119): bwe_get_acf()
#1 /Users/alexanderpersky/Sites/wordpress/wp-includes/rest-api/class-wp-rest-server.php(936): bwe_get_posts(Object(WP_REST_Request))
#2 /Users/alexanderpersky/Sites/wordpress/wp-includes/rest-api/class-wp-rest-server.php(321): WP_REST_Server->dispatch(Object(WP_REST_Request))
#3 /Users/alexanderpersky/Sites/wordpress/wp-includes/rest-api.php(266): WP_REST_Server->serve_request('/better-rest-en...')
#4 /Users/alexanderpersky/Sites/wordpress/wp-includes/class-wp-hook.php(286): rest_api_loaded(Object(WP))
#5 /Users/alexanderpersky/Sites/wordpress/wp-includes/class-wp-hook.php(310): WP_Hook->apply_filters('', Array)
#6 /Users/alexanderpersky/Sites/wordpress/wp-includes/plugin.php(515): WP_Hook->do_action(Array) in /Users/alexanderpersky/Sites/wordpress/wp-content/plugins/better-rest-endpoints/includes/get_acf.php on line 12

Filter the output of JSON

Thank you for creating such an excellent wordpress REST API plugin, it enhances the output of JSON.This feature helps me a lot:

the official API:

/wp-json/wp/v2/posts?categories=5

this outputs only category 5's posts not including its children categories posts

and better-rest-endpoints API:

/wp-json/better-rest-endpoints/v1/posts?category=5

this outputs all posts of category 5 including all its children categories posts

appreciate for your excellent works!

Now I have a little suggestion about filtering the output of JSON.

Can we add a filter parameter to the API's endpoints to filter the output of JSON? For example:

if wen can use:

/wp-json/better-rest-endpoints/v1/posts?category=5&fields=id,title,date

(query string &fields=id,title,date is added)

to output only the id title date fields, thus the JSON output will be much smaller.

Many thanks! Wish you a happy life!

ACF with translations to rest api

m using wp rest api to create a decouple website. At this moment i already can recieve data from homepage with this call(using a plugin to make json from api pretty):

mydomain.com/wp-json/better-rest-endpoints/v1/page/homepage and mydomain.com/en/wp-json/better-rest-endpoints/v1/page/homepage

this 2 calls work just fine but, when i create another page for example about-me and make the same calls

mydomain.com/wp-json/better-rest-endpoints/v1/page/about-me and mydomain.com/en/wp-json/better-rest-endpoints/v1/page/about-me

the main language works just fine bue the translation (in this case English) is returning null on ACF object.

is something wrong? the way that i made the translations is the same on both cases

Query Order Params

Add params for all queries/endpoint so that the order can be adjusted, such as random, asc, desc, etc.

Remove `copy.js` from repo.

This file was never meant to be included in the repo.

Get Post by Slug

Would be nice to get a post by slug, since we might not know the ID at a certain point in the application.

ACF Post Object not returning permalink

Hello,

I'm not sure if this is even an issue with BRE or not but when retrieving custom post type posts with ACF Post Object fields, I'm getting the post objects array but the data does not include the post object/post permalink.

Is there a way to add the post object permalink endpoint to BRE programmatically?

Thanks!

Undefined variable $bre_page in get_page_by_id.php

When I attempt to hit an endpoint for a page (e.g. /wp-json/better-rest-endpoints/v1/page/3) that is in draft mode, I get the following error:

Notice: Undefined variable: bre_page in web/app/plugins/better-rest-endpoints/includes/get_page_by_id.php on line 103

This is because you've defined the $bre_page variable inside the while() loop, and are trying to access it in the conditional.

  if( $query->have_posts() ){
    while( $query->have_posts() ) {
      ...

      $bre_page = new stdClass();
    
      ....

  }  else {
      return $bre_page;  // <-- This guy
  }

ACF Options page endpoint

Hey

Great plugin. I was wondering if there was a way to access Advanced custom fields through an endpoint or if there is anything in the pipeline to expose this.

E.g better-rest-endpoints/v1/options/{options-page-slug}

Taxonomy Endpoints

Need to add taxonomy endpoints, for instance a slim down version of something like this:

http://example.dev/wp-json/wp/v2/{taxonomy}

ACF Clone Fields

ACF Clone fields double up in their responses. This may be more on the ACF side of things so it might be worth looking into how we can alter their responses.

Query string to hide featured media from response

Add a query string for collections to hide media object from response.

ie ?media=false

Add permalink to responses

Only GET method?

Is possible to use POST, DELETE, ...?
I get a 404 error

support exclude_tag and exclude_category for /search and /posts

It would be great if I could filter out specific categories or tags. Seems like 'category__not_in' and 'tag__not_in' would do the trick.

Yoast SEO data not coming for posts of specific category

We are getting data for individual posts including the yoast meta but not the meta set for categories or tag in Yoast

offset parameter

Thanks for the great plugin.
However, would be great to have ?offset as an option amongst the available parameters.

Get Posts by Custom Taxonimies

Similar to #3 - but to get posts belonging to that Custom Tax.

Bug with <!--more--> tag

I'm using Wordpress v5.2.2
The plugin i'm using is v1.5.2

When /v1/post/{id/slug} or /v1/posts has tag in content data the rest of the content won't show up

The Original Post

The JSON Response

Get Page by ID, when the page is a Post Archive, returns the incorrect data

I have a page called "Blog" which I have configured as the "Posts Page" via WP Settings -> Reading. This page's ID is 20. I then have a couple of test posts created, with the intention of building a post archive template from this data.

However, when I query the endpoint better-rest-endpoints/v1/page/20, I get the following response:

{
    id: 25,
    title: "Pluto is definitely a planet",
    slug: "pluto-is-definitely-a-planet",
    permalink: "domain/pluto-is-definitely-a-planet/",
    template: "default",
    content: "<p>TRUST ME! Don&#8217;t listen to Neil DeGrasse Tyson.</p> ",
    parent: false,
    acf: null,
    yoast: null,
    media: false
}

This is actually the data pertaining to the most recent post which would be shown within that archive, as opposed to what you'd expect to return (the data for the actual archive page itself, i.e. { id; 20, title: "Blog", slug: "blog", permalink: "domain/blog/", etc etc. }). When I visit the default WP REST API endpoint for this page (wp/v2/pages/20) I do get the correct object in response.

Query String to hide ACF fields

Would be nice to have a query string to allow ACF fields to be hidden. Such as acf=false. Would be useful in cases where you're building routes in an app and just want to return the bare minimum response.

Get posts by acf (filter)

Hello there...

I like a lot your plugin. I want to use it to improve my requests.

But I have a problem. One of my requests is to get posts by acf field value. With default rest api and wp rest filter plugin, it is possible to do via
/posts?filter[meta_key]=key&filter[meta_value]=value
that gives me list of posts with
acf: { key: value }

Is it possible to do with your plugin? I'm confused a bit. I tried to do this via 'orderby=meta_value_num' like in codex and other options trying filtering, but I can't receive needed result.

Thanks in advance.

Exlcude paramater is returning null

https://wp.****.com/wp-json/better-rest-endpoints/v1/posts?per_page=9&page=1&exclude=null&author=&category_name=content

^ example