Make WordPress Core

Opened 6 years ago

Closed 4 years ago

Last modified 4 years ago

#44326 closed enhancement (fixed)

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

Reported by: earnjam's profile earnjam Owned by: earnjam's profile 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 6 years ago.
44326.2.diff (5.8 KB) - added by earnjam 5 years ago.

Download all attachments as: .zip

Change History (15)

6 years ago

#1 @earnjam
6 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.

5 years ago

#3 @TimothyBlynJacobs
5 years 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
5 years 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
5 years ago

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

#6 @TimothyBlynJacobs
5 years ago

tax_relation sounds good to me!

5 years ago

#7 @earnjam
5 years 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.

5 years ago

#9 @TimothyBlynJacobs
4 years 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
4 years 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
4 years ago

  • Milestone changed from Future Release to 5.4

#12 @audrasjb
4 years ago

  • Keywords needs-dev-note added

#13 @desrosj
4 years ago

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

This was detailed in the following dev note:

Note: See TracTickets for help on using tickets.