Human readable URLs

[MortenHofft]

Currently URLs on hosted portals are encoded and unreadable for humans. e.g. filter=eyJtdXN0Ijp7InllYXIiOlt7InR5cGUiOiJlcXVhbHMiLCJ2YWx1ZSI6IjIwMDAifV19fQ%3D%3D&from=0 would really just be year=2000 on gbif.org and the APIv1.

But the new search supports richer filters. For example LIKE predicates and NOT for some fields. E.g. searching for occurrences that do NOT have issue ZERO_COORDINATE. And it allows searching by wildcard like recordedBy LIKE *humboldt*. These 2 examples cannot be expressed in our APIv1 (GET syntax).

That raises the question. If we want to have human readable URLs for the new search how do we go about it? Do we require the "human" URLs to be APIv1 compatible?

• Version 1: As long as the query can be translated to APIv1 like year=2000, then do so, if not, then flip into an encoded state like filter=eyJtdX....
• Version 2: Strive to make it human readable but with an extended syntax. E.g. issue NOT ZERO_COORDINATE could become !issue=ZERO_COORDINATE. It isn't APIv1 compatible, but it is easier to read and fiddle with than filter=eyJtdX.... Like could be recordedBy~=*humboldt*

Version 1 would of course strive to be compatible with v1. So if we later decided to extend the APIv1 REST syntax with negation (what ever syntax we then decide on), then we would start serialising that as well instead of doing filter=eyJtdX... for negations.

[timrobertson100]

My guess is that many people are accustomed to hacking the URL both to craft filters on GBIF.org, and then for some to subsequently convert that into an equivalent API call if they are scripting things. It's my workflow.

Because of this, and since this will affect GBIF.org shortly as well as the hosted portals, I'd recommend the safer option of version 1 for the time being.

I suggest we explore if we can add negations, wildcards, and nullability checks to the REST API regardless, which would then allow richer filters to be exposed in the human-readable form consistently (i.e. accommodating option 2 but keeping the API compatibility).

A good addition would be an easy way for web users to convert to an equivalent API call (REST or GraphQL) removing the reliance on URL hacking and allowing more freedom for web development.

[MortenHofft]

Closed https://github.com/gbif/gbif-web/commit/2a79c5e399badf7e61bc4552af0a2c4b4164e96a

[MortenHofft]

I've implemented a version that is keeping strictly to our APIv1. If a filter is composed that isn't compatible with v1, then it will flip into using an encoded state.

so a filter for "occurrences from year 200" will become year=2000 as that is API v1 compatible but a filter for "occurrences with a year" till become filter=749noone876canreadthis... as that is not compatible with current v1

past urls will continue to work, but will be rewritten once the user starts fiddling with the UI.

[MortenHofft]

It is available in our test environment for now https://hp-theme.gbif-uat.org/occurrence/search?country=DK&taxonKey=1&year=2000

[timrobertson100]

This looks great to me. All my usual URL hacks work naturally.

[MortenHofft]

this is now in production. Old urls will continue to work.