[MGNLREST-317] DOC: Update filtering operators docs re: contains use case Created: 06/Jul/21  Updated: 11/Apr/22

Status: Selected
Project: Magnolia REST Framework
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Medium
Reporter: Scot Rhodes Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: Zip Archive apps-demo-light-module.zip    
Template:
Acceptance criteria:
Empty
Task DoD:
[ ]* Doc/release notes changes? Comment present?
[ ]* Downstream builds green?
[ ]* Solution information and context easily available?
[ ]* Tests
[ ]* FixVersion filled and not yet released
[ ]  Architecture Decision Record (ADR)
Documentation update required:
Yes
Story Points: 2

 Description   

When filtering multi-value properties, it's not obvious how to achieve a "contains" strategy—the [in] operator might be attempted, but is intended for other purposes (ranges/dates).

As stated in the comments, this is actually somewhat more simple:

  • /.rest/delivery/tours/v1?tourTypes=415025c6-e4b5-4506-9384-34f428a52104 actually behaves as "contains".
  • For "all-of" filtering, just repeat the parameter => /.rest/delivery/tours/v1?tourTypes=415025c6-e4b5-4506-9384-34f428a52104&tourTypes=e007e401-1bf8-4658-8293-b9c743784264

At the moment, the filter operators table in docs explains how the query-param operands translate into JCR queries. This is not very useful, since user should not be expected to know how JCR works underneath.

See https://docs.magnolia-cms.com/product-docs/6.2/Developing/API/Delivery-API.html#_filter_operators.

Original description:

We should be able to filter a Rest Call to include some sort of "CONTAINS" capability so that if you are filtering against a list of something like UUID's, the result would be only items that contain the requested ID. 

I'm including example code from two Content Apps, and the goal would be to query the Products which has a Multi-Value property of ProductCategories, requesting that the ProductCategory ID is contained in that list. So the request should look something like:

[http://localhost:8080/magnoliaAuthor/.rest/delivery/products?categories[contains]=98a69699-0acd-4d8d-b743-9d9fb2b9830a|http://localhost:8080/magnoliaAuthor/.rest/delivery/products?categories[in]=522df173-51a3-40f0-b831-5f67d4e0157f]

And the result would start with something like:

{
  "results": [
    {
      "@name": "blabla22",
      "@path": "/blabla22",
      "@id": "a95f310f-f418-4b0a-be7d-4d77943428b5",
      "@nodeType": "mgnl:content",
      "price": "551.34",
      "categories": [
        "98a69699-0acd-4d8d-b743-9d9fb2b9830a",
        "ae5dae88-488b-43ac-b857-b142d2fa3c33"
      ],
      "title": "Red Bag",
      "name": "blabla22",
      "images": [
        
      ],

Some import data is included for testing.

 



 Comments   
Comment by Scot Rhodes [ 06/Jul/21 ]

This request was made, and turns out the functionality already exists. Could we get some documentation added to the Delivery REST API page to specify that a filter request against a list with a UUID will return a proper result? This is the equivalent "CONTAINS" that I was looking for. For a bit more clarification, if you have a multi-value property like this:

      "categories": [
        "98a69699-0acd-4d8d-b743-9d9fb2b9830a",
        "ae5dae88-488b-43ac-b857-b142d2fa3c33"
      ],

And you perform a filter on the REST call like this:

http://localhost:8080/magnoliaAuthor/.rest/delivery/products?categories=ae5dae88-488b-43ac-b857-b142d2fa3c33

You would get that result in return.

 

Generated at Mon Feb 12 06:58:44 CET 2024 using Jira 9.4.2#940002-sha1:46d1a51de284217efdcb32434eab47a99af2938b.