PDS API documents are unclear wrt quoting in queries

[msbentley]

Checked for duplicates

No - I haven't checked

🐛 Describe the bug

When searching for data with the PDS API, it is unclear when and what kind of quotes are required in query strings.

The docs suggest this should work:

pds:Time_Coordinates.pds:start_date_time gt 2001-05-10T00:00:00Z

but it doesn't seem to. Neither does

pds:Time_Coordinates.pds:start_date_time gt '2001-05-10T00:00:00Z'

however this works OK:

pds:Time_Coordinates.pds:start_date_time gt "2001-05-10T00:00:00Z"

🕵️ Expected behavior

I expected that the documents or a return error message explain what kind of quoting is needed.

📜 To Reproduce

Execute the query as above.

⚙️ Engineering Details

Acceptance Criteria

• [x] Documentation examples use correct syntax/quoting.
• [x] Self-documentation explicitly specifies double-quotes.
• [x] Detailed specifications on Github contain or link to query-string syntax specification

[jordanpadams]

@tloubrieu-jpl @alexdunnjpl can you take a look here as well!

[alexdunnjpl]

@msbentley when referencing use of the API, are you using the swagger docs, the API documentation, both, or neither?

The API documents syntax correctly details the format for query strings

{literal value} is either a string between " (double quotes) or a numerical value (float or integer)

but that does no good if it's not easy to find, so feedback on that would be useful.

Likewise, the API self-documentation (redirects from https://pds.nasa.gov/api/search/) states

syntax: q="vid eq 13.0"

behavior: query uses eq,ne,gt,ge,lt,le,(,),not,and,or operators. Properties are named as in 'properties' attributes, literals are strings between quotes, like "animal", or numbers. Detailed query specification is available at https://bit.ly/3h3D54T

note: ignored when keyword is present

(though this should explicitly specify double-quotes - @jordanpadams, is this documentation generated from SwaggerHub or elsewhere? Also the linked detailed query specification doesn't actually include a "Query sting syntax" section, despite referring to it, which we should fix)

Not trying to RTFM you @msbentley , just understand exactly where the existing doco is failing.

[msbentley]

Hi @alexdunnjpl I was using the API docs (first link in your reply), and in particular the examples shown in the query syntax section:

It's true that the if I had read the full doc I would have found the double quotes mention, but I was lazy and trying to work from examples ;-)

[alexdunnjpl]

@msbentley kind of a reasonable assumption that if you plug in the examples, they'll work 😅

I'll work through the docs and fix any discrepancies like that.

[msbentley]

Thanks @alexdunnjpl - that same table also contains examples that don't work because they use "fake" attributes to query on, so it would also be good to update those, e.g.

target_name eq “Mars” and instrument_name eq “hirise”

[alexdunnjpl]

Agreed. @jordanpadams @tloubrieu-jpl do you have any suggestions for an example query that is meaningful/instructive and near-guaranteed to return a nonzero result set? Or should I just assume that what's in prod will always be and I can use what's currently there?

Presumably we want to link to the /properties endpoint in that part of the docs, once it's released.