navigating documentation was a bit difficult

A user worked with us to add this study to NMDC: https://data.microbiomedata.org/?q=Ch4IABABGAMiFiJubWRjOnN0eS0xMS1lNHliOXo1OCI

She recently emailed me asking

"I'm trying to show my student the searchable BRC terms with the API to incentivize what our vision is — I know there is a link in some running notes we've had in the past. Do you have the link by chance?"

I responded and explained

"Here you go: https://api.microbiomedata.org/docs#/find/find_biosamples_biosamples_get If you’re on any of the https://data.microbiomedata.org/pages, we have a “products” tab that will take you to the API, submission portal, edge, and data portal 😊 Also, it has changes, so now to pull all the metadata associated with your study, you’re going to use the filter command “associated_studies:nmdc:sty-11-e4yb9z58”"

However, that wasn't totally intuitive, and she had follow up questions.

"Can you send me the specific API call to pull the metadata? For example, to pull the study, I'd use: https://api.microbiomedata.org/studies/nmdc%3Asty-11-e4yb9z58 I'm not sure where to put the filter command."

I think she meant which "filter, search, sort" ... and I wanted to share some documentation to her.

My initial search, clicking on "Documentation" at the top of the API page took me to here: https://microbiomedata.github.io/nmdc-runtime/
Seeing the "Submit metadata as JSON" in the Tutorials & "Authoring Changesheets" in How-To- Guides, I was like hmm, that's not right...
Then I found https://nmdc-documentation.readthedocs.io/en/latest/howto_guides/api_gui.html
- This seemed more like what I was looking for & I sent this to the user.

However, this hasn't been updated & still has "part_of" for the search.

I have not heard back from this user to know if my extended clarification & documentation link helped.

This is what I said "If you’re looking for the biosamples metadata, you’ll use the exact link I have below. The “find” section has a “get /biosamples” and in the “filter” box you’ll put “associated_studies:nmdc:sty-11-e4yb9z58” We have a how- to-guide here: https://nmdc-documentation.readthedocs.io/en/latest/howto_guides/api_gui.html It needs updated, part_of is now associated_studies to search for a biosample’s metadata."

Hopefully this worked for the user, but knowing to go to the "find" section, and knowing to use "filter" was not intuitive. Let alone the requirement of knowing to use "associated_studies" as the criteria.

microbiomedata / nmdc-runtime

navigating documentation was a bit difficult #777