Look up repository information by ID

[bryanbraun]

The API supports Github repository lookup by ID (here's an example: https://api.github.com/repositories/18749335).

In Octokit, the repository methods allow you to input a repo full_name (example here) to get repository info.

It would be really convenient to lookup information by ID as well, because doing a call with a stored full_name can fail when somebody changes their username or repo name.

[pengwynn]

I'm torn on this one. We could make it work by allowing Repository to be initialized with an integer and making it smart enough to build either repos/:owner/:name or repositories/:id based on its attributes.

Or we could bite the bullet and use hypermedia internally. We've held off on this approach until we felt setting up HTTP caching was automatic or super easy. I'm not sure we're there yet.

Thoughts @joeyw?

[joeyw]

@pengwynn The api currently returns a 404 for moved repositories. I think the api should be changed to mimic the GitHub website behavior of redirecting to the updated repository. Then we can figure out how to best handle that with octokit.

[pengwynn]

We should definitely handle redirects if/when the API supports that.

I read the current question as something like: given that IDs are guaranteed not to change and I have a repository ID, can I just use that in Octokit and not have to worry about renames?

Does that sound right, @bryanbraun?

Instead of supporting :owner/:name and :id for all the methods, I'd rather encourage consumers to store and use hypermedia URLs. That's the direction we've taken some of the newest API methods.

You can already do this today with the lower-level hypermedia client, but there's some value in having convenience methods in the client for some of those API methods.

I've got my own use cases, but @bryanbraun I'm interested in hearing yours and what prompted the feature request.

[joeyw]

Hypermedia urls would still fail in this case because of the lack of redirects.

The only reason to us an :id instead of a name is because the :id doesn't change. Which sounds exactly like a URL to me.

I don't oppose a method of looking up by :id. I think it is the wrong solution to this problem in this case.

[pengwynn]

Hypermedia urls would still fail in this case because of the lack of redirects.

Sorry, should have explicitly said ID-based URLs. Those won't redirect.

We return those from the API in pagination headers today and will mostly likely migrate all link relations to ID-based URLs.

[pengwynn]

ID-based URLs won't redirect for a renamed repository.

[bryanbraun]

@pengwynn, to further elaborate on the use-case, suppose my application provides a dashboard for tracking information about some of your own repos, with various statistics on the projects. When users flag projects to add them to their dashboard I'd need to store a reference for each project they add.

The ID is best because it doesn't change, but all of Octokit's methods to get data about a repository ask you to do lookup by full_name. Here are a few examples of how I'm doing it in my own code:

  # Get github project star count
  def get_star_count(full_name)
    star_count = client.repository(full_name).stargazers_count
  rescue Octokit::NotFound
    nil
  end

  # Get github project issue count
  def get_issue_count(full_name)
    issue_count = client.repository(full_name).open_issues_count
  rescue Octokit::NotFound
    nil
  end

  # Get github project forks count
  def get_fork_count(full_name)
    forks_count = client.repository(full_name).forks_count
  rescue Octokit::NotFound
    nil
  end

  # Get github project pull request count
  def get_pull_request_count(full_name)
    pull_request_count = client.pull_requests(full_name, :state => 'open').length
  rescue Octokit::NotFound
    nil
  end

If I store full names of projects, I'd have to build in a way to check if the full_name is still accurate, and if not, find out if that means there was a rename or the project was deleted. I'd need conditions for each situation, and all this means more complexity and API calls. Unfortunately, I cannot let webhooks do the heavy lifting because there are no events for deleting or renaming repositories.

Finally, for my specific application, I expect the repo names to change, because users can clone repos based off a template repo, in a manner similar to @benbalter 's copy-to utility. I expect users to then rename their cloned project.

If you can think of an alternate approach to lookup-by-id, then let me know. 😃

[joeyw]

Added in #485