Incomplete information about limitations of REST API for code search

[brabster]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/rest/search/search?apiVersion=2022-11-28

What part(s) of the article would you like to see updated?

I think this documentation should clearly call out that the REST API uses a legacy search syntax, the limitations of the REST code search API as described over in the legacy docs, and that results via the API are unlikely to match the results obtained through the web interface.

I just wasted a few hours building a tool to search for untrusted GitHub actions, only to discover it appeared to work well on the first couple of orgs I tried it on, but then missing results on the third led me to find the legacy docs that explained why it wasn't working (max 2 fragments, only recently-searched repos 🤦)

There are three limitations outlined in the doc, but there are ten in the full list. Had I been directed at the full list, I think it would have been clear that it was not fit for my purpose without wasting my time.

Additional information

I can submit a PR for the main doc, but I spent most of my time in the API documentation which is where the partial list of limitations is. It looks like that section is generated and not editable?

[welcome]

Thanks for opening this issue. A GitHub docs team member should be by to give feedback soon. In the meantime, please check out the contributing guidelines.

[Sharra-writes]

@brabster Thanks so much for opening an issue! It is true that some of the REST API documentation is generated and has to be fixed internally. I'll get this triaged for review, and then we'll know what the limitations are!

[github-actions]

Thanks for opening an issue! We've triaged this issue for technical review by a subject matter expert 👀

[Sharra-writes]

@brabster This will definitely need to be looked at internally, but I haven't transferred it yet because I've been trying to find out why it wasn't already documented. I'll let you know if I get an answer, but I may end up having to send it over to the team to look into in more depth.

[Sharra-writes]

No one seems to have answers on this, so I'm going to transfer it internally to be examined.

[docs-bot]

Thank you for opening this issue! Updates to this documentation must be made internally. I have copied your issue to an internal issue, so I will close this issue.