[MGNLREST-181] Stripping language suffixes from properties in requests with the lang param might lead to problems Created: 16/Mar/18  Updated: 31/Aug/21  Resolved: 31/Aug/21

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

Type: Improvement Priority: Neutral
Reporter: Martin Drápela Assignee: Unassigned
Resolution: Obsolete Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Relates
relates to DOCU-1390 Delivery endpoint: how to filter on s... Closed
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)
Date of First Response:
Story Points: 8

 Description   

In v2 delivery endpoint we strip language suffixes from property names if one passes the lang param in the request and its value is anything but all.

This however leads to absurd i18n situations which may lead to further i18n problems if one decides to work with the content of the response (JSON or XML).

I think that the property name should be shown in the REST API response in exactly the same form as in what is actually in the JCR repo.


Consider the following scenario (tested with a 5.6.4-snap CE bundle):

1) Define a simple endpoint called ep for the tours module:

class: info.magnolia.rest.delivery.jcr.v2.JcrDeliveryEndpointDefinition
workspace: tours
includeSystemProperties: false

2) Find a tour whose description is Get photobombed by a Sea Turtle and request only the content variant in the German language:

http://localhost:8080/magnoliaAuthor/.rest/ep/?description=Get%20photobombed%20by%20a%20Sea%20Turtle&lang=de-DE
{
  "results": [
    {
      "@name": "Scuba-Diving-in-Bahamas--famed-Tiger-Beach",
      "@path": "/magnolia-travels/Scuba-Diving-in-Bahamas--famed-Tiger-Beach",
      "@id": "82cc787a-0bf1-4561-859f-adea4c12ab2f",
      "@nodeType": "mgnl:content",
      "isFeatured": "true",
      "name": "Tauchen am Tiger Beach",
      "description": "Lassen Sie sich von einer Meeresschildkröte überraschen, die plötzlich auf Ihrem Foto erscheint",
      "location": "Miami, USA",
      "tourTypes": [
        "d2245867-ecaa-4b4e-8743-e0c939be68b7",
        "eaf9a648-fae1-48ae-a293-69bed874f159"
      ],
      "author": "Magnolia Travels",
      "body": "<p>Unsere beliebteste aktive Tour f&uuml;hrt zum weltber&uuml;hmten Tiger Beach in den Gew&auml;ssern vor den Bahamas. Dieser spektakul&auml;re Ort ist einmalig in der Welt. Magnolia Travels garantiert Ihnen eine der einzigstartigen Unterwasser-Erfahrungen &uuml;berhaupt. Umgeben vom kristallblauen Wasser der Bahamas und perlwei&szlig;em Sand k&ouml;nnen Sie Ammenhaie, Riffhaie, Zitronenhaie und Tigerhaie beobachten. Bringen Sie Ihre Kamera mit, es gibt auf dieser Reise keinen Mangel an gro&szlig;artigen Foto- oder Videogelegenheiten. &nbsp;</p>\n<p>Auf dieser Expedition haben Sie Gelegenheit, mit unseren entz&uuml;ckenden und ber&uuml;hmten Tigerhai-&bdquo;Supermodels&ldquo; von Angesicht zu Angesicht zu tauchen:&nbsp; Emma, Baby Cakes, Tanya, Begonia und Mini-T. Unsere &bdquo;Supermodel&ldquo; werden Ihnen dabei helfen, einige der weltweit besten Hai-Fotos zu schie&szlig;en. Sie lieben es, f&uuml;r die Kamera zu l&auml;cheln!</p>\n<p>Nat&uuml;rlich w&auml;re keine Reise auf die Bahamas vollst&auml;ndig ohne Tauchen in den umwerfenden und vielfarbigen Riffen. Sie sind von einer F&uuml;lle kleiner und gro&szlig;er Meereslebewesen umgeben;&nbsp; Sch&ouml;nheit und Wunder dieses vibriendenden &Ouml;kosystems lassen Sie verstummen. Karibische Riffhaie, gro&szlig;e Zackenbarsche, Mur&auml;nenaale und viele andere Fische wetteifern um Ihre Aufmerksamkeit, w&auml;hrend Sie &uuml;ber vielf&auml;ltige Korallenarten, wellenf&ouml;rmige Seef&auml;cher und eine bunte Anordnung von Schw&auml;mmen gleiten. Beginnen Sie noch heute, mit uns Ihre Erinnerungen zu gestalten!</p> ",
      "destination": [
        "ed3dcd18-78af-46df-a9e1-bc732479f2e7"
      ],
      "duration": "14",
      "image": "jcr:795449d2-6c16-402e-9e8a-bbb101fe22bb",
      "@nodes": []
    }
  ]
}

Now let's work with the result returned further. The result says that the description property for tour with id 82cc787a-0bf1-4561-859f-adea4c12ab2f  is

Lassen Sie sich von einer Meeresschildkröte überraschen, die plötzlich auf Ihrem Foto erscheint

3) Find a tour whose description is then Lassen Sie sich von einer Meeresschildkröte überraschen, die plötzlich auf Ihrem Foto erscheint. The request above clearly shows there is one like that and it should have the id 82cc787a-0bf1-4561-859f-adea4c12ab2f:

http://localhost:8080/magnoliaAuthor/.rest/ep/?description=Lassen%20Sie%20sich%20von%20einer%20Meeresschildkr%C3%B6te%20%C3%BCberraschen%2C%20die%20pl%C3%B6tzlich%20auf%20Ihrem%20Foto%20erscheint

However what we get is:

{
  "results": []
}


 Comments   
Comment by Martin Drápela [ 16/Mar/18 ]

An afterthought: the whole result would have to be "wrapped" into "language": "de-DE" or something like that but I think this just adds another level of complexity for the person who wants to work with the REST API response further down the line.

Comment by Christopher Zimmermann [ 19/Mar/18 ]

I agree that there needs to be a way a good way to filter for items that are in different languages.

But I disagree that the responses should have the language suffixes (ie .. "description_de"). The developer of client of the REST endpoint should not have to do special things to work with the properties in different languages - they should only have to work with the defined name of the properties  (ie "description"), as is currently implemented. In the same way that a template author need only work with the defined property names.

Comment by Mikaël Geljić [ 19/Mar/18 ]

I'll recap bits from our chat with mdrapela last Friday, unfortunately no silver bullet right now:

  • JCR queries are executed first, while the "i18n-wrapping" comes last;
  • While we could search for both "description" and "description_de" when you pass a lang param, this could lead to false positives, because we don't know when a property is i18n'ed or not (wait for content types).

Nonetheless, I would argue that the case "I'm filtering only nodes whose 'x' property is <painfully long sentence here>" is quite unrealistic. Consequently, I suggest we document the current status as is, and close this as Won't Fix.

Filters and Localized content

Query filters are applied against exact JCR property names. This means that filtering an i18n'ed property cannot be done in locale-independent manner. To mitigate this, here's a few points to consider:

When user is expected to type arbitrary literal input, full-text search is most often a better alternative (?q=...); Magnolia's Search configuration works over translated content.

As an alternative, when user is expected to select one of several translated values, filters may be used by appending the locale suffix (e.g. _fr) to the property name, hence targeting the exact JCR property name.

Comment by Christopher Zimmermann [ 20/Mar/18 ]

I agree fulltext search is very common. But especially with the filter operators I think its a normal usecase that a client of the API wants to filter with text in a specific language.

Tours app doesnt have the most convincing usecase as is - but lets imagine that the "Start city" field was localized. A french client wants to search for tours in "Bâle" instead of in "Basel" A scenario could be something like Im using a MTravels smart phone app and I've switched to browse in French. At some point I want to search for things in a particular city - in French.

I would think that when a request specifies the language with the "lang" parameter or accept header, that all filters would operate against the properties of that language. What do you think?

 

 

Comment by Mikaël Geljić [ 20/Mar/18 ]

czimmermann, I agree this seems like the "natural" way things should work; however I enjoin you to read again the two bullet points in my previous reply. This cannot be done without significant design changes, not so much in rest, but with respect to Content I18n in Magnolia. You don't know what you query until you get the results.
Again, this stands as long as we don't have more info about the model (which properties are i18n'ed and which are not). A ContentTypeDeliveryEndpoint would likely be better at figuring this out.

Re: start-city use case, wouldn't you rather extract cities (at least) to a separate content-app, and perform full-text search over these?
Chance is that you don't want editors to translate the same cities every time on each tour. First search for the city, select it, and perform the filter with an ID. That's also how I imagine such a UI filter—effectively an autocomplete field to a 3rd-party service—would work.

I'm also trying to come up with other hypothetical use cases, like a description filter in a table, but then I find it hard to imagine that users would not select a locale first (not to have the same tour showing up n times in different langs), which would make the suffix alternative viable.

mdrapela Can't users still achieve what you describe with lang=all? (effectively disabling i18n-wrapping and returning all properties as they are)

Comment by Christopher Zimmermann [ 21/Mar/18 ]

False positives problem with searching description and description_de, hmm tricky. I wonder if a user would prefer falsepositives to getting nothing? Ahh, but the "ne" and "not-in" operators would cause problems. 

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