Make WordPress Core

Opened 2 years ago

Closed 9 months ago

Last modified 6 weeks ago

#44326 closed enhancement (fixed)

Add relation parameter to REST API /wp/v2/posts endpoint

Reported by: earnjam Owned by: earnjam
Milestone: 5.4 Priority: normal
Severity: normal Version: 4.7
Component: REST API Keywords: has-unit-tests has-patch has-dev-note
Focuses: rest-api Cc:


The REST API /wp/v2/posts endpoint allows filtering by terms across multiple taxonomies, but it always uses an AND relationship between them.


Translates to:
All posts with Tag 1 AND Category 2

WP_Query supports passing a relation parameter when running a tax query across multiple taxonomies. It defaults to AND, which is what we do now, but it would be nice to support the ability to specify OR here as well.

Attachments (2)

44326.diff (5.8 KB) - added by earnjam 2 years ago.
44326.2.diff (5.8 KB) - added by earnjam 11 months ago.

Download all attachments as: .zip

Change History (15)

2 years ago

#1 @earnjam
2 years ago


  • Adds a new parameter to the /wp/v2/posts endpoint called relation which accepts AND or OR. If left off, it defaults to the current functionality of AND.
  • Adds 2 new tests

This ticket was mentioned in Slack in #core-restapi by timothybjacobs. View the logs.

14 months ago

#3 @TimothyBlynJacobs
14 months ago

  • Keywords needs-refresh added; has-patch removed
  • Milestone changed from Awaiting Review to Future Release

This looks good to me!

I think we just need a different query parameter name that is a bit more specific to the term query. Perhaps terms_relation?

#4 @earnjam
14 months ago

Thanks! I chose relation since that was the name of the parameter in WP_Query, though I can see how that is pretty vague. I like term_relation, but I wonder if it should be something like tax_relation since it's the relationship between the taxonomies, not the individual terms.

This ticket actually spun out of #41287, which is for supporting the use an AND relationship between terms within a single taxonomy. I think the two would pair up nicely to extend what is possible through the API.

#5 @earnjam
14 months ago

  • Owner set to earnjam
  • Status changed from new to accepted

#6 @TimothyBlynJacobs
13 months ago

tax_relation sounds good to me!

11 months ago

#7 @earnjam
11 months ago

  • Keywords has-patch added; needs-refresh removed

44326.2.diff just updates the naming to tax_relation

This ticket was mentioned in Slack in #core-restapi by earnjam. View the logs.

11 months ago

#9 @TimothyBlynJacobs
9 months ago

  • Resolution set to fixed
  • Status changed from accepted to closed

In 46646:

REST API: Add tax relation parameter to posts collection.

The REST API supports filtering by terms across multiple taxonomies using an AND relation. This adds support for an OR relation by adding "tax_relation=OR" as a query parameter.

Props earnjam.
Fixes #44326.

#10 @SergeyBiryukov
9 months ago

In 46648:

REST API: Set orderby parameter in tax relation unit tests added in [46646].

The default value of date caused a race condition resulting in random test failures.

See #44326.

#11 @TimothyBlynJacobs
9 months ago

  • Milestone changed from Future Release to 5.4

#12 @audrasjb
7 months ago

  • Keywords needs-dev-note added

#13 @desrosj
6 weeks ago

  • Keywords has-dev-note added; needs-dev-note removed

This was detailed in the following dev note: https://make.wordpress.org/core/2020/02/29/rest-api-changes-in-5-4/

Note: See TracTickets for help on using tickets.