Invitation methods take :owner/:repo #586
Conversation
All repository routes on the GitHub API can accessed via /repositories/:id _and_ /repos/:owner/:repo. For whatever reason, the documentation for the invitation routes only references the former. Repository invitations are the only functions in google/go-github to use the :id style routes, so I'd propose we change them to use :owner/:repo as that will likely be much more convenient for users of this library.
|
Hmm, this is very interesting. On the surface, what you're saying is very true. I want to dig deeper to better understand how this happened and what's going on. These methods were implemented 9 months ago, in #373, and reviewed by @gmlewis and me. At first, I thought this was about one of the new features we've merged in the last few days, but 9 months? I'm surprised no one has spotted this before now. Looking at the GitHub announcement the underlying issue was about, and then the documentation, I can see how this happened. The GitHub documentation actually uses repo IDs rather than owner/repo scheme.
(Source: https://developer.github.com/v3/repos/invitations/#list-invitations-for-a-repository.) As you said, both are indeed valid, but this library and most endpoints in GitHub API docs use the latter form. I think we should contact GitHub support and ask them about this. Perhaps there's a good reason why these endpoints are documented using repo ID form rather than owner/repo. If so, we'll need to think harder about this. Otherwise, and I suspect this is the case, it could be just an unintended outcome. If so, they might decide to fix their documentation to use the consistent owner/repo form. If that happens, it should be much easier for us to make the decision to follow suit. Given that this has been around for 9 months, it's a little worrisome about breaking the API... but unless I'm missing something, this alternate form must be more awkward to use anyway. Also, these endpoints are still considered as "preview API", it's not yet stable version, which gives us more room to fix things. |
|
@shurcooL Here's what I got from GitHub support
In my specific case, I'm trying to plug this API into code that only has |
|
Hmmm... I'm now wondering if we should have another Maybe that is overkill... but I'm not sure I like breaking this API here either when both methods of access should be possible via the API. Of course, a GraphQL version of the API should solve this, but we aren't there yet. |
|
Thanks for emailing them.
That's great to hear, and I think that gives us a good chance of being able to fix up this unintended inconsistency in the API.
@gmlewis I think it'd be better to have a discussion about such a large and sweeping potential change in a separate issue. I'm really worried about anything that increases API sizes, and doubling is very significant. That said, I want to refer you to some relevant previous issues on the topic. Consider #68, which I think proposed a very good approach for being able to use both owner/repo and ID-based ways of referring to repositories, users. Unfortunately, it didn't make it in because it was too late to make such a breaking API change. |
|
Thanks for the pointer, @shurcooL, I had not seen that. Very clever. |
Let's do that. |
There was a problem hiding this comment.
I've reviewed the change, LGTM. Thanks @alindeman.
Let's just bump up the library version number in github.go.
|
Great, thanks! You all will take the integration from here? |
|
It would be helpful if you, @alindeman, bump the library version number in |
@gmlewis Sure, done. |
|
Ok, merging. |
All repository routes on the GitHub API can accessed via /repositories/:id and /repos/:owner/:repo. For some reason, the documentation for the invitation routes only references the former. Contacting GitHub support has confirmed that the inconsistent documentation was unintentional and will likely be corrected to use :owner/:repo soon. Repository invitations are the only functions in google/go-github to use the :id style routes, so this changes them to use :owner/:repo for consistency, and as that will likely be much more convenient for users of this library. Bump version because this is a breaking API change. It affects endpoints that are part of preview API only.
All repository routes on the GitHub API can accessed via /repositories/:id and /repos/:owner/:repo. For whatever reason, the documentation for the invitation routes only references the former, but both work correctly.
Repository invitations are the only functions in google/go-github to use the :id style routes, so I'd propose we change them to use :owner/:repo as that will likely be much more convenient for users of this library.