“get a reference” API does not accept SHAs as documented (`/repos/{owner}/{repo}/git/ref/{ref}`)

[flying-sheep]

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?

The docs for this endpoint say /repos/{owner}/{repo}/git/ref/{ref}:

ref string Required

The commit reference. Can be a commit SHA, branch name (heads/BRANCH_NAME), or tag name (tags/TAG_NAME). For more information, see "Git References" in the Git documentation.

(emphasis mine)

Yet the ref API responds with 404 when used with a (valid) commit SHA:

$ gh api repos/scverse/anndata/git/ref/a4786471ee4d4e894fec150e426c3551db0f31e0
gh: Not Found (HTTP 404)
{
  "message": "Not Found",
  "documentation_url": "https://docs.github.com/rest/git/refs#get-a-reference"
}

whereas the commits API works:

$ gh api repos/scverse/anndata/commits/a4786471ee4d4e894fec150e426c3551db0f31e0
{
  "sha": "a4786471ee4d4e894fec150e426c3551db0f31e0",
  "node_id": "C_kwDOBfZ26doAKGE0Nzg2NDcxZWU0ZDRlODk0ZmVjMTUwZTQyNmMzNTUxZGIwZjMxZTA",
  "commit": {...},
  ...
}

using the ref API with e.g. branch also works as documented:

$ gh api repos/scverse/anndata/git/ref/heads/main
{
  "ref": "refs/heads/main",
  "node_id": "MDM6UmVmMTAwMDM4Mzc3OnJlZnMvaGVhZHMvbWFpbg==",
  "url": "https://api.github.com/repos/scverse/anndata/git/refs/heads/main",
  "object": {
    "sha": "a4786471ee4d4e894fec150e426c3551db0f31e0",
    "type": "commit",
    "url": "https://api.github.com/repos/scverse/anndata/git/commits/a4786471ee4d4e894fec150e426c3551db0f31e0"
  }
}

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

Either the documentation for the ref path parameter needs to be updated or the ref API needs to start working with commits as documented.

Additional information

No response

[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.

[nguyenalex836]

@flying-sheep Thanks for opening this issue! I'll get this triaged for review ✨

[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.

[flying-sheep]

What will the fix be? Will the definition of the ref parameter change or the behavior of the API? Where can I track this?

[lsdm83114]

Ref parameters change behavior in the API

[lsdm83114]

Ref parameters change behavior in the API~~~~

[flying-sheep]

The documentation now reads

ref string Required

The Git reference. For more information, see "Git References" in the Git documentation.

So I assume that means “commit sha” isn’t supposed to be a valid option?

Can you please clarify what the resolution here is?

[skedwards88]

The description for that endpoint says

The :ref in the URL must be formatted as heads/ for branches and tags/ for tags. If the :ref doesn't match an existing ref, a 404 is returned.

So I think that the SHA is not accepted. I'll open an internal issue to move that info into the ref parameter description to make it more discoverable.