Rethinking additional search views URLs

[obulat]

The additional search views IP proposed to use the path parameters for tag, creator and source values: /images/source/flickr/, /images/source/flickr/creator/someone, /images/tag/tag name. Path parameters make the URLs more readable, easier to share, easier to cache and perform cache invalidation required by #1969.

However, this proposal did not take into the account the fact that the creator names and tag names can have the special characters that are significant for URL path parsing: / and ?. Encoding these characters using encodeURIComponent converts them to %2F and %3F, however, routers, proxy servers often treat the URL-encoded and non-URL-encoded versions of these symbols interchangeably. Browsers (specifically Firefox) also automatically decode these symbols even when they are URL-encoded. So, when you enter https://staging.openverse.org/image/source/flickr/creator/me%2Fyou in the address bar, the browser requests https://staging.openverse.org/image/source/flickr/creator/me/you.

Alternative solutions

1. Encoding the values twice

Allow using special characters in creator name and tags uses a twice-encoded value for the / and ? special characters, both for the frontend and the API. For instance, creator/name?me is encoded as creator%252Fname%253Fme. This allows us to keep using the path parameters for all of their benefits. Besides, this would not require considerable changes to the API/frontend code, and changing the API version.

The drawback of this solution is that it would introduce an unexpected requirement for the users to encode the path parameters twice. It would also prevent the pattern of typing the URL in clear text and expecting the browser to correctly handle this URl.
In general, this solution is "fighting the URL path/browser standards".

2. Convert the path parameters to query parameters

Query parameters are expected to be URL-encoded, so we are using the standards.
One option is to have the following paths:

Frontend

https://openverse.org/image/collection?tag=tag
https://openverse.org/image/collection?source=flickr
https://openverse.org/image/collection?source=flickr&creator=creator%2Fname

API

https://api.openverse.engineering/v2/image/collection?tag=tag
https://api.openverse.engineering/v2/image/collection?source=flickr
https://api.openverse.engineering/v2/image/collection?source=flickr&creator=creator%2Fname

We would have to handle the edge case when the user sets all of the parameters: https://api.openverse.engineering/v2/image/collection?source=flickr&creator=creator%2Fname&tag=tag%20name . One option would be to drop the last one.

The drawbacks are:

• API version needs to be updated since we will be removing the paths from the production.
• Significant code changes necessary, both in the API and in the frontend.
• Less readable and cacheable URLs

My preference would be the first option. The main reasons are that the working solution is available in #3793, and can document the requirement to encode the path parameters in a special way (and add this note to the error message on the endpoint), and won't need to update the API version.

@sarayourfriend's preference is the second option, with the reasons given in the PR comment.

@WordPress/openverse-api , @WordPress/openverse-frontend, what do you think?

[zackkrida]

Thank you for writing this up! This is also a general issue concerning data sanitation across Openverse. My thoughts on what is best:

Providers

Providers already have url-safe and readable provider identifiers. These are fine to use as paths.

• Example: animaldiversity for "Animal Diversity Web"
• observe with curl https://api.openverse.engineering/v1/images/stats/ | jq 'map({source_name,display_name})'

Tags

Tags are a property of the Openverse API, identifiers used for filtering and to express relationships between records, so I am of the opinion these should be sanitized and normalized to be url-safe and not require any encoding as well.

Creators

Creator names are text data belonging to our records. As such they need to be preserved exactly. These are not identifiers. The closest thing we store as a unique identifier for the creator is the creator URL. The creator name is not appropriate for a URL path. Options we could take are:

• Use a ?creator=creator%2fname query parameter. This feels fine, since these are essentially sub-filtered provider views anyway.
• Start generating computed, unique creator identifiers for use in Elasticsearch, something like {provider-slug}_{creator-name-slug}.
  • For example, this artist "Holger Klein/Helmholtz-Gemeinschaft" from Wikimedia Commons would become wikimedia-audio_holger-klein-helmholtz-gemeinschaft and the url to match them would be https://staging.openverse.org/audio/source/wikimedia_audio/holger-klein-helmholtz-gemeinschaft

[sarayourfriend]

Tags are a property of the Openverse API, identifiers used for filtering and to express relationships between records, so I am of the opinion these should be sanitized and normalized to be url-safe and not require any encoding as well.

What kind of sanitization are you suggestion? HTTP doesn't support unicode in URL components. How would we handle accents, or non-latin script? Are they all URL encoded in the path (thereby making them unreadable when copying the URL)?

We do not do any tag normalisation other than lowercasing them for search, and they are not linked data, because there is not even a standardisation between seemingly identical identifiers, e.g., "cats", "Cat", "cat", "CAT", "CATS" are all strictly different, even if our full text search encoding normalises them to lowercase. On top of that, "gato", "chat", etc are also different, despite being the same term, especially when considering these applied to images where an image of a cat is not dependent on the language of the person who tagged it (it's an image of a cat regardless of the language). There is also zero linking between related terms like "feline" and "cat", or family terms like "lion", "tiger", "house cat", and so forth, all of which would require much more involvement when ingesting tags and building a graph of linked terms. There was also at one point a (bad) attempt at "deburring" which we still need to fix (#1927).

express relationships between records

This is an incidental relationship, not one we actually control. That's the crux of the issue. It's also a massively complex issue to just rely on URL encoding tags when considering anything other than non-accented latin script.

The distinction you're drawing between identifiers and non-identifiers, is not sound, not unless we essentially completely overhaul how we handle tags. So long as tags are raw user input, with no processing or linking between related terms, we cannot seriously consider them identifiers. And because we don't have any confidence marker on tags, they aren't even necessarily a reliable relationship marker.

We'd need an entirely new project, including a lot of research and planning, to be able to consider tags as reliable identifiers controlled by Openverse, so long as we are allowing user input into tags (e.g., Flickr).

For creator names, the same issue with respect to non-latin script applies. We'd need to create a completely unrelated identifier (like a UUID) to have something reliable and that doesn't unduly prioritise European languages. Consider a Japanese fan of the national rugby team (ブレイブ・ブロッサムズ) having their creator name on Openverse turned into %E3%83%96%E3%83%AC%E3%82%A4%E3%83%96%E3%83%BB%E3%83%96%E3%83%AD%E3%83%83%E3%82%B5%E3%83%A0%E3%82%BA.

[zackkrida]

My thoughts on what is best

Quoting myself, I should've been more explicit that my answer was a little more aspirational than practical. I also apologize for that because I don't think it's what @obulat was looking for.

This is an incidental relationship, not one we actually control.
The distinction you're drawing between identifiers and non-identifiers, is not sound

Agreed. Despite that, the concept of the tag pages is predicated on the fact that they have some relational meaning across providers; that there's some (however tenuous) link between images marked "cat" on Flickr and "cat" on StockSnap and so on. I agree it's an incidental relationship but it is one we're intentionally surfacing! We either shouldn't do that or should plan to improve that system.

I feel that a half-measure of some light cleanup (case normalization, certain character removal [forward slashes]), preserving accents [so we don't match dads to potatoes in Spanish, for example], even if it prioritizes non-latin script and users, would still be very beneficial.

Also, I've observed some interesting browser sugar when it comes to encoding:

Firefox for me renders some unicode characters, for example:

• https://en.wikipedia.org/wiki/Möbius_strip
  

• https://ru.wikipedia.org/wiki/%D0%9D%D1%8C%D1%8E-%D0%99%D0%BE%D1%80%D0%BA_(%D1%88%D1%82%D0%B0%D1%82)
  

• https://unsplash.com/ja/s/%E5%86%99%E7%9C%9F/%E3%83%90%E3%83%81%E3%82%AB%E3%83%B3%E5%B8%82%E5%9B%BD
  

On Debian 12 I'm able to copy/paste the https://en.wikipedia.org/wiki/Möbius_strip url without it being converted to the encoding, not the others.

[zackkrida]

Ah, and apologies, you address the browser cleartext thing in one of the linked comments, @sarayourfriend

[zackkrida]

Edit: I need to sit with this a bit more before replying. My original reply was a little rash and didn't actually choose from the proposed solutions. It was more of an aspirational description of how things should be rather than choosing a path forward.

[obulat]

After a comment on why having slashes in the frontend path parameters is not possible, and whether it is a Nuxt issue, I went back to the Nuxt path parsing implementation, and now I think I'm with @sarayourfriend on this. We should probably plan refactoring the paths to use URL query parameters for tag and creator, since the values are not sanitized, and the way the path is parsed is not fully compatible with the way we want to use it.

Frontend / and ? parsing

The most problematic characters in path are / and ? as they are used as path parameter and path/query dividers. Interestingly, the browser behavior is also slightly different when a path contains more than one question mark.
In the tag view, Firefox seems to URI-encode all of the special characters, and Chrome - all but the last question mark. This means that when you enter a tag in clear case like this: http://localhost:8443/image/tag/animals/cats&dogs?page=2, it is parsed as

{ path_params: { tag: 'animals/cats%26dogs?page=2' }, query: {} }

in one browser, and

{ path_params: { tag: 'animals/cats%26dogs' }, query: {page=2} }

in another.

Existing data

I looked in the catalog for examples of creator names that contain /. Here are some of the longest one that contain various special characters:

1. Kolforn (Kolforn)I'd appreciate if you could mail me ([Kolforn@gmail.com](mailto:Kolforn@gmail.com)) if you want to use this picture out of the Wikimedia project scope. .mw-parser-output .responsive-license-cc{clear:both;text-align:center;box-sizing:border-box;width:100%;justify-content:space-around;align-items:center;margin:0.5em auto;background-color:#f9f9f9;border:2px solid #e0e0e0;border-spacing:8px;display:flex}.mw-parser-output .responsive-license-cc div{margin:4px}.mw-parser-output .rlicense-text div{margin:0.5em auto}@media screen and (max-width:640px){.mw-parser-output .responsive-license-cc{flex-flow:column}.mw-parser-output .rlicense-text{order:1}}This file is licensed under the Creative Commons Attribution-Share Alike 4.0 International license. You are free: to share – to copy, distribute and transmit the work to remix – to adapt the work Under the following conditions: attribution – You must give appropriate credit, provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use. share alike – If you remix, transform, or build upon the material, you must distribute your contributions under the same or compatible license as the original.https://creativecommons.org/licenses/by-sa/4.0CC BY-SA 4.0 Creative Commons Attribution-Share Alike 4.0 truetrue
2. https://www.mod.go.jp/msdf/index.html 海上自衛隊
3. bDom [+7 Mio views - + 90 K images/photos]

Planning for additionas search views paths

If we decide to refactor the additional search views paths, in addition to the URLs I suggested in the first message here, we could also use the following structure (considering that source always uses characters that can be used in a path parameter):

Frontend
https://openverse.org/image/collection?tag=tag
https://openverse.org/image/collection/source/flickr/
https://openverse.org/image/collection/source/flickr?creator=creator%2Fname

API
https://api.openverse.engineering/v2/image/collection?tag=tag
https://api.openverse.engineering/v2/image/collection/source/flickr
https://api.openverse.engineering/v2/image/collection/source/flickr?creator=creator%2Fname

This would be somewhat similar to the way we structure the search URLs now: if there's no path parameter, we show ALL media types, otherwise, only the media of the type in the path parameter (/search?q=cat, search/image?q=cat and search/audio?q=cat).
So, we can use a path parameter for source, and show source or (if the creator query parameter is available) creator collection. If we decide to show "license" or "category" (or some other collection category that only allows specific set of options) media, we could use it like that: image/collection/category/digitized_artwork.

[sarayourfriend]

I agree with the query parameter approach (of course).

I wonder if creating distinct views is the best though, now that we have seen the potential pitfalls. Our search API already supports creator, tag, and source searches. tags is fuzzy matching, but we can use some modifier or the tag parameter as a distinct exact match if that is really what we still want. We can take the opportunity to use more distinct approaches to searches that do not include a q parameter, taking the "collections" strategy approach instead, which has better performance and the sensible sorting-by-indexation-date behaviours, which would be welcome in non-q based searches generally.

If we do go with the new collection endpoint rather than using the existing collections strategy for searches that do not have q parameter on the regular search endpoint, it would be good to name it unstable__collection for the time being, so we can be sure to figure out all the edge cases as we go along, rather than being surprised by them and needing to rollback versioned APIs that do not work.

To clarify, the collection route on the frontend makes perfect sense to me, I'm asking here just about the API side.

Either way, I am still in full support of using query parameters for this for all the reasons you've outlined.

To clarify also, this would have at least two issues, right? One to fix the API side, and another to fix the frontend side? The API side I think could be done realistically in a single PR, but the frontend seems more complex to me. Would it need to be multiple different issues?

[zackkrida]

Plus one to the approach of using the properly utf-8 encoded query params, and the "bonus" path-based routes on the frontend for source collections.

On the frontend, we'll want to make sure we set the rel="canonical" tag properly so that the path-based source collections are seen as the canonical versions of those pages by search engines. That is assuming we're going to allow search engines to index these (which I think we should!).

I also agree with @sarayourfriend's suggestions for the API, and the general concept of trying to move these searches into our image and audio search endpoints rather than having dedicated api endpoints for these collections (provided I'm understanding @sarayourfriend correctly!).

I'm happy to work on any of these frontend issues when the time comes as well 😄

[sarayourfriend]

Olga and I discussed this synchronously today, and we landed on the following decisions:

API changes

filter request like /(audio|image)\/(tag|source)/
| filter isempty(http_referrer)
| filter http_user_agent not like "Openverse"

Delete the three (six) new endpoints

Build the collections strategy into existing search endpoint, hidden behind unstable__collections query parameter.

Frontend

Reduce the number of pages down to just 1. This change makes things much simpler for us.

We landed on this being the best one, we would like to switch to:

/collection?tag=...
/collection?source=...
/collection?source=...&creator=...

This is 1 page, rather than several, per media type.

Olga asks what to do when the query parameters conflict or don't make sense. We just 404. If it doesn't have a query parameter, 404. If it has creator but no source, 404. If it has tag and source, 404. etc. Do not try to support people adding their own query parameters, etc. Only support navigating to the page, and copy/pasting it.

We also thought about this:

/collections?tag=...
/source/:source
/source/:source?creator=...

But rejected it because /collection is just simpler and has more long term flexibility.

Question: whether path parameters are better for SEO in any way. It doesn't seem like it would be the case, because the issues for SEO according to this page Olga linked, the main issue is the number of possible URLs, and that stays the same regardless of whether it's a path or query parameter.

Updating the plan

We'll move the existing plan(s) into a subfolder of the project's directory named something like "superseded", and then write a new version (based on the existing plan) outlining the approach we've decided on above, with a note at the top of the new document indicating that this is a plan written after we started implementation, and ran into issues with the first plan.

That way we preserve the history of the project in an easy-to-reference way, without creating confusion about what the current plan is and why we have chosen it over the previously agreed upon plan.

[sarayourfriend]

@obulat will you create issues for these? I can create one for the API work, but I'm not comfortable giving issue-level directions on the frontend changes, in particular, how to breakdown the changes into manageable PRs.

[obulat]

I opened a PR with the IP update: #3868, and issues for the Frontend and API changes.