Per-repository Review and Issue Comment listing

You've always been able to grab all the commit comments for an entire repository via the API, but to get Issue comments and Pull Request Review Comments, you could only fetch the comments for a single Issue or Pull Request.

Today, we're introducing two new methods to grab all Issue Comments and Review Comments for a repository.

# Grab all Issue Comments
curl https://api.github.com/repos/mathiasbynens/dotfiles/issues/comments

# Grab all Review Comments
curl https://api.github.com/repos/mathiasbynens/dotfiles/pulls/comments

Check out the docs for sorting and filtering options:

Gitignore Templates API

We recently made it easy to initialize a repository when you create it via the API. One of the options you can pass when creating a repository is gitignore_template. This value is the name of one of the templates from the public GitHub .gitignore repository.

The Gitignore Templates API makes it easy to list those templates:

curl https://api.github.com/gitignore/templates

HTTP/1.1 200 OK

[
  "Actionscript",
  "Android",
  "AppceleratorTitanium",
  "Autotools",
  "Bancha",
  "C",
  "C++",
  ...

If you'd like to view the source, you can also fetch a single template.

curl -H 'Accept: application/vnd.github.raw' \
     https://api.github.com/gitignore/templates/Objective-C

HTTP/1.1 200 OK

# Xcode
.DS_Store
build/
*.pbxuser
!default.pbxuser
*.mode1v3
!default.mode1v3
*.mode2v3
!default.mode2v3
*.perspectivev3
!default.perspectivev3
*.xcworkspace
!default.xcworkspace
xcuserdata
profile
*.moved-aside
DerivedData
.idea/

Forking to Organizations

We made a slight change to the way you fork a repository. By default, you can fork my repository through an HTTP POST to the repository's fork resource.

curl -X POST https://api.github.com/repos/technoweenie/faraday/forks

This repository forks to your personal account. However, there are cases when you want to fork to one of your organizations instead. The previous method required a ?org query parameter:

curl -X POST /repos/technoweenie/faraday/forks?org=mycompany

Query parameters on POST requests are unusual in APIs, and definitely inconsistent with the rest of the GitHub API. You should be able to post a JSON body like every other POST endpoint. Now, you can! Only, now we're calling the field organization.

curl /repos/technoweenie/faraday/forks?org=mycompany \
 -d '{"organization": "mycompany"}'

Don't worry, we are committed to maintaining the legacy behavior until the next major change of the GitHub API.

Gist comment URIs

The URIs of all gist comments are changing immediately. The new URI pattern for gist comments is /gists/{gist-id}/comments/{id}. (See gist comments section of the docs for more details.) This change is necessary because the auto-incremented ids of gist comments are easy to guess. This predictability allows anyone to view comments on private Gists with relative ease. Obviously, comments on private gists should be just as private as the gist itself.

Adding the gist id to the URI of comments makes it impossible, in practical terms, to guess that URI because the id of private gists are very large random numbers. This is, unfortunately, a breaking change but one that cannot be avoided because of the security implications of the current URIs. We apologize for the inconvenience.

We have also added a comments_url member to the Gist documents. The comments_url link provides access to the comments of a Gist in a way that will insulate clients from changes in the URI patterns used by the GitHub API. We are increasing our use of links in order to make changes such as this one less damaging to clients. We strongly encourage using url and *_url properties, where possible, rather than constructing URIs using the patterns published on this site. Doing so will result in clients that break less often.

Notifications API

Now that the dust has settled around Notifications and Stars, we've unleashed all that :sparkles: in a brand new API. You can now view and mark notifications as read.

Endpoint

The core notifications functionality is under the /notifications endpoint. You can look for unread notifications:

curl https://api.github.com/notifications

You can filter these notifications to a single Repository:

curl https://api.github.com/repos/technoweenie/faraday/notifications

You can mark them as read:

# all notifications
curl https://api.github.com/notifications \
   -X PUT -d '{"read": true}'

# notifications for a single repository
curl https://api.github.com/repos/technoweenie/faraday/notifications \
   -X PUT -d '{"read": true}'

You can also modify subscriptions for a Repository or a single thread.

# subscription details for the thread (either an Issue or Commit)
curl https://api.github.com/notifications/threads/1/subscription

# subscription details for a whole Repository.
curl https://api.github.com/repos/technoweenie/faraday/subscription

Polling

The Notifications API is optimized for polling by the last modified time:

# Add authentication to your requests
curl -I https://api.github.com/notifications
HTTP/1.1 200 OK
Last-Modified: Thu, 25 Oct 2012 15:16:27 GMT
X-Poll-Interval: 60

# Pass the Last-Modified header exactly
curl -I https://api.github.com/notifications
   -H "If-Modified-Since: Thu, 25 Oct 2012 15:16:27 GMT"
HTTP/1.1 304 Not Modified
X-Poll-Interval: 60

You can read about the API details in depth in the Notifications documentation.

Set the default branch for a repository

You can set the default branch for a repository to something other than 'master' from the GitHub repository admin screen:

repo admin

Now, you can update this setting via the API. We've added a default_branch parameter to the Edit Repository method:

curl -u pengwynn \
     -d '{"name": "octokit", "default_branch":"development"}' \
     https://api.github.com/repos/octokit/octokit.rb

If you provide a branch name that hasn't been pushed to GitHub, we'll gracefully fall back to 'master' or the first branch.

Organization Members Resource Changes

Requesting the member list of an organization of which you are not a member now redirects to the public members list. Similarly, requests to membership check resources of an organization of which you are not a member are redirected to the equivalent public membership check. One exception to the latter case is that if you are checking about your own membership the request is not redirected. You are always allowed to know what organizations you belong to.

The changes where made to clarify the purpose of these various resources. The /orgs/:org/members resources are intended for use by members of the organization in question. The /orgs/:org/public_members resources are for acquiring information about the public membership of organizations. If you are not a member you are not allowed to see private membership information so you should be using the public membership resources.

If you have any questions or feedback, please drop us a line.

Rate limit changes for unauthenticated requests

To ensure a high quality of service for all API consumers, we've reduced the default rate limit for unauthenticated requests. To enjoy the default rate limit of 5,000 requests per hour, you'll need to authenticate via Basic Auth or OAuth. Unauthenticated requests will be limited to 60 per hour unless you include your OAuth client and secret.

We'll soon require all requests to include a valid User Agent header. Setting a unique value for this header helps us identify requests and get in touch with developers who are abusing the API. Most HTTP libraries, wrapper libraries, and even cURL provide a valid header for you already and allow you to change it to something unique to your application.

If you have any questions or feedback, please drop us a line.

Initialize a repository when creating

Today we've made it easier to add commits to a repository via the GitHub API. Until now, you could create a repository, but you would need to initialize it locally via your Git client before adding any commits via the API.

Now you can optionally init a repository when it's created by sending true for the auto_init parameter:

curl -i -u pengwynn \
     -d '{"name": "create-repo-test", "auto_init": true}' \
     https://api.github.com/user/repos

The resulting repository will have a README stub and an initial commit.

create repo screenshot

.gitignore templates

Along with this change, you can set up your .gitignore template by passing the basename of any template in the GitHub gitignore templates project.

curl -i -u pengwynn \
     -d '{"name": "create-repo-test", "auto_init": true, \
          "gitignore_template": "Haskell"}' \
     https://api.github.com/user/repos

As the docs point out, the gitignore_template parameter is ignored if auto_init is not present and true.

If you have any questions or feedback, drop us a line at https://github.com/contact or @GitHubAPI.

Upcoming Changes to Watcher and Star APIs

We recently changed the Watcher behavior on GitHub. What used to be known as "Watching" is now "Starring". Starring is basically a way to bookmark interesting repositories. Watching is a way to indicate that you want to receive email or web notifications on a Repository.

This works well on GitHub.com, but poses a problem for the GitHub API. How do we change this in a way that developers can gracefully upgrade their applications? We're currently looking at rolling out the changes in three phases over an extended period of time.

Current Status

The current Repository Starring methods look like this:

  • /repos/:owner/:repo/watchers - A list of users starring the repository.
  • /users/:user/watched - A list of repositories that a user has starred.
  • /user/watched - A list of repositories the current user has starred.

Phase 1: Add Watchers as Subscriptions

This phase exposes Watchers as "Subscriptions". This is to keep from clashing with the legacy endpoints. This phase will happen automatically and will not break your application until Phase 3 starts. (UPDATE: API v3 will continue to support this functionality indefinitely.)

  • /repos/:owner/:repo/subscribers - A list of users watching the repository.
  • /users/:user/subscriptions - A list of repositories that a user is watching.
  • /user/subscriptions - A list of repositories the current user is watching.

We'll also add a copy of the legacy Watchers API in the new endpoint:

  • /repos/:owner/:repo/stargazers - A list of users starring the repository.
  • /users/:user/starred - A list of repositories that a user has starred.
  • /user/starred - A list of repositories the current user has starred.

This is in place now with the current media type for the API:

application/vnd.github.beta+json

If you care about your application not breaking, make sure all outgoing API requests pass that value for the "Accept" header. You should do this now. This can be verified by checking the X-GitHub-Media-Type header on all API responses.

# Accesses a user's starred repositories.
curl https://api.github.com/user/watched \
 -H "Accept: application/vnd.github.beta+json"

-This Phase will be broken once Phase 3 starts. Phase 3 removes all support for the "beta" media type, and makes the "v3" media type the implicit default for API requests.

UPDATE - November 6, 2013

API v3 will continue to officially support the functionality described in Phase 1 above. This functionality will remain intact for the lifetime of API v3.

API v3 will not include Phases 2 and 3 (below). Those phases will likely be part of the next major version of the API. (We have not announced a timeline for the next major version of the API.)

Phase 2: Switch /watchers API Endpoint

The "watch" endpoints will now be a copy of the "subscription" endpoints. You will have to use /user/starred to get a user's starred repositories, not /user/watched.

This requires a new media type value:

application/vnd.github.v3+json

This is a breaking change from Phase 1. We will release this change in an experimental mode first, letting developers gracefully upgrade their applications by specifying the new media value for the Accept header.

# Accesses a user's watched repositories.
curl https://api.github.com/user/watched \
  -H "Accept: application/vnd.github.v3+json"

Phase 3: Remove /subscribers API Endpoint.

This phase involves disabling the subscription endpoints completely. At this point, you should be using the starring endpoints for starred repositories, and the watch endpoints for watched repositories. No date has been set yet, but we expect this to be 3-6 months after Phase 2 is in place. This should give developers enough time for a smooth upgrade path. If they use popular API wrappers, the work will likely mostly be done for them.

Keep on passing the "v3" media type in your application, until the API has another breaking change to make. If you can't make the deadline for Phase 3, just set the "beta" media type until we shut that down completely. It's likely that we will keep the old "beta" media type active for another month, like the last time we terminated old API functionality.

We look forward to assisting you through this transition. Hit us up at https://github.com/contact or @GitHubAPI.