Confusing ref format mismatch between updateReference vs createReference

[billytrend]

updateReference takes a partially qualified ref { ref: "tags/x" ... } because it is interpolated into PATCH /repos/:owner/:repo/git/refs/:ref

createReference takes a fully qualified ref { ref: "refs/tags/x" ... } because it is passed in the body of a request

This also affects other ref operations.

The difference here is very confusing and has caught me out a couple of times. Is there a way I can manually update the docs to highlight this?

Thanks

[gr2m]

Hey there, thanks for opening the issue. The docs cannot be updated manually right now, the endpoint methods are based on the REST API docs at https://developer.github.com/v3

This is something I’ve run into in the past myself. I think I brought it up with the docs/API team before, I think there was a legid reason for why it is the way it is, but I agree that it could at least be mentioned in the docs. Let me look into it again

[billytrend]

Well the behaviour makes complete sense to me from the sdk codegen point of view since the create request is explicitly defined as /refs/:ref and I'd imagine you extract url variables programmatically into fields? Not sure there would be a good way of automating around this unless you have some ability to manually override the code that is produced.

[gr2m]

I will check in with the REST API team to see if we can skip the /refs prefix for the "Create a reference" endpoint.

I’ve looked trough the routes and these are the ones that include a ref parameter. I’m sure the API/docs could be more consistent here, I’ll discuss it with the docs/API team

ref can be SHA, branch name, or a tag name

• GET /repos/:owner/:repo/commits/:ref/check-runs - https://developer.github.com/v3/checks/runs/#list-check-runs-for-a-specific-ref
• GET /repos/:owner/:repo/commits/:ref/check-suites - https://developer.github.com/v3/checks/suites/#list-check-suites-for-a-specific-ref
• GET /repos/:owner/:repo/readme - https://developer.github.com/v3/repos/contents/#get-the-readme
• GET /repos/:owner/:repo/contents/:path - https://developer.github.com/v3/repos/contents/#get-contents
• GET /repos/:owner/:repo/deployments - https://developer.github.com/v3/repos/deployments/#list-deployments
• POST /repos/:owner/:repo/deployments - https://developer.github.com/v3/repos/deployments/#create-a-deployment
• GET /repos/:owner/:repo/commits/:ref/statuses - https://developer.github.com/v3/repos/statuses/#list-statuses-for-a-specific-ref
• GET /repos/:owner/:repo/commits/:ref/status - https://developer.github.com/v3/repos/statuses/#get-the-combined-status-for-a-specific-ref
• GET /repos/:owner/:repo/:archive_format/:ref - https://developer.github.com/v3/repos/contents/#get-archive-link

ref must be heads/branch-name, not just branch-name

• GET /repos/:owner/:repo/git/refs/:ref - https://developer.github.com/v3/git/refs/#get-a-reference

Not mentioned in the docs, but I assume

• PATCH /repos/:owner/:repo/git/refs/:ref - https://developer.github.com/v3/git/refs/#update-a-reference
• DELETE /repos/:owner/:repo/git/refs/:ref - https://developer.github.com/v3/git/refs/#delete-a-reference

ref must be a fully qualified reference (ie: refs/heads/master)

• POST /repos/:owner/:repo/git/refs - https://developer.github.com/v3/git/refs/#create-a-reference

unclear

Will ask API team to clarify :)

• GET /repos/:owner/:repo/commits/:ref - https://developer.github.com/v3/repos/commits/#get-the-sha-1-of-a-commit-reference

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[bcoe]

I was fairly confused by this myself; am I following that this is expected behavior, but the difference in behavior is not reflected in docs?

[gr2m]

I tested the GET /repos/:owner/:repo/commits/:ref endpoint and it looks like the handling changed,ref can be any of the following

• a commit sha
• a branch name
• heads/<branch name>
• refs/heads/<branch name>
• a tag name
• tags/<tag>
• refs/tags/<tag name>

The same is true for

• GET /repos/:owner/:repo/:archive_format/:ref
• GET /repos/:owner/:repo/commits/:ref/check-runs
• GET /repos/:owner/:repo/commits/:ref/check-suites

I'd appreciate help with testing the remaining API endpoints

I tested POST /repos/:owner/:repo/git/refs: the ref parameter must be a fully qualified reference name, but that is documented and the server responds with a helpful error if it's not. But I do wonder why that is, and if the handling could be adjusted to accept a "ref" without the refs/ prefix.

[gr2m]

Closing this issue due to inactivity and outdated docs/links. If there is still anything actionable left, let's discuss it here:
https://github.com/octokit/octokit.js/discussions