API Changes

Releases API

This summer we made it easier to release your software. Today, you can fully automate those releases via the Releases API Preview.

This API is a little different due to the binary assets. We use the Accept header for content negotation when requesting a release asset. Pass a standard API media type to get the API representation:

$ curl -i -H "Authorization: token TOKEN" \
     -H "Accept: application/vnd.github.manifold-preview" \
     "https://uploads.github.com/repos/hubot/singularity/releases/assets/123"

HTTP/1.1 200 OK

{
  "id": 123,
...
}

Pass “application/octet-stream” to download the binary content.

$ curl -i -H "Authorization: token TOKEN" \
     -H "Accept: application/octet-stream" \
     "https://uploads.github.com/repos/hubot/singularity/releases/assets/123"

HTTP/1.1 302 Found

Uploads are handled by a single request to a companion “uploads.github.com” service.

$ curl -H "Authorization: token TOKEN" \
     -H "Accept: application/vnd.github.manifold-preview" \
     -H "Content-Type: application/zip" \
     --data-binary @build/mac/package.zip \
     "https://uploads.github.com/repos/hubot/singularity/releases/123/assets?name=1.0.0-mac.zip"

Preview mode

The new API is available as a preview. This gives developers a chance to provide feedback on the direction of the API before we freeze changes. We expect to lift the preview status in 30 days.

As with the Search API, we’ll take this opportunity to iterate quickly. Breaking changes will be announced on this developer blog without any advance warning. Once the preview period is over, we’ll consider the Releases API unchangeable. At that point, it will be stable and suitable for production use.

The preview media type is “application/vnd.github.manifold-preview”. Manifold is a member of the Avengers, with the ability to teleport through time and space. He’s the one in the middle holding the spear.

Manifold teleporting the Avengers to a terraformed Mars surface

Two-Factor Authentication and the API

As announced earlier today, GitHub.com now supports two-factor authentication (2FA) for increased security. For users with this feature enabled, GitHub.com will prompt for a 2FA code in addition to a username and password during authentication. We’ve also rolled out some improvements to the API to ensure that 2FA requirements in the API are consistent with GitHub.com.

Authenticating with the API

For users without 2FA enabled, and for applications using the OAuth web flow for authentication, everything is business as usual. You’ll continue to authenticate with the API just as you always have. (That was easy.)

If you enable 2FA and use Basic Authentication to access the API, we’re providing multiple options to make the flow simple and easy.

Basic Authentication and 2FA

Personal Access Tokens

Personal access tokens provide the simplest option for using 2FA with Basic Authentication. You can create these tokens via the application settings page on GitHub.com, and you can revoke them at any time. For more information about authenticating to the API with personal access tokens, be sure to check out our help article on the topic.

Tightly-integrated 2FA

For developers wishing to integrate GitHub 2FA directly into their application, the API’s Basic Authentication now supports the ability to send the user’s 2FA code, in addition to the username and password.

We’re here to help

We think GitHub users are going to love the additional security provided by two-factor authentication. As always, if you have any questions or feedback, let us know. We’re here to help!

Improvements to the Search API

Today we’re shipping two improvements to the new Search API.

More Text Match Metadata

When searching for code, the API previously provided text match metadata (i.e., “highlights”) for file content. Now, you can also get this metadata for matches that occur within the file path.

For example, when searching for files that have “client” in their path, the results include this match for lib/octokit/client/commits.rb:

{
  "name": "commits.rb",
  "path": "lib/octokit/client/commits.rb",
  "text_matches": [
    {
      "object_url": "https://api.github.com/repositories/417862/contents/lib/octokit/client/commits.rb?ref=8d487ab06ccef463aa9f5412a56f1a2f1fa4dc88",
      "object_type": "FileContent",
      "property": "path",
      "fragment": "lib/octokit/client/commits.rb",
      "matches": [
        {
          "text": "client",
          "indices": [ 12, 18 ]
        }
      ]
    }
  ]
  // ...
}

Better Text Match Metadata

Before today, the API applied HTML entity encoding to all fragment data. For example, imagine your search returns an issue like rails/rails#11889:

Example Issue Title

The response would include a text_matches array with the following object:

{
  "fragment": "undefined method `except' for #<Array:XXX>",
  // ...
}

Inside the fragment value, we see HTML-encoded entities (e.g., <). Since we’re returning JSON (not HTML), API clients might not expect any HTML-encoded text. As of today, the API returns these fragments without this extraneous encoding.

{
  "fragment": "undefined method `except' for #<Array:XXX>",
  // ...
}

Preview Period

We’re about halfway through the preview period for the new Search API. We appreciate everyone that has provided feedback so far. Please keep it coming!

Preview the New Search API

Today we’re excited to announce a brand new Search API. Whether you’re searching for code, repositories, issues, or users, all the query abilities of github.com are now available via the API as well.

Maybe you want to find popular Tetris implementations written in Assembly. We’ve got you covered. Or perhaps you’re looking for new gems that are using Octokit.rb. No problem. The possibilites are endless.

Highlights

On github.com, we enjoy the context provided by code snippets and highlights in search results.

code-snippet-highlighting

We want API consumers to have access to that information as well. So, API requests can opt to receive those text fragments in the response. Each fragment is accompanied by numeric offsets identifying the exact location of each matching search term.

Preview period

We’re making this new API available today for developers to preview. We think developers are going to love it, but we want to get your feedback before we declare the Search API “final” and “unchangeable.” We expect the preview period to last for roughly 60 days.

As we discover opportunities to improve this new API during the preview period, we may ship changes that break clients using the preview version of the API. We want to iterate quickly. To do so, we will announce any changes here (on the developer blog), but we will not provide any advance notice.

At the end of preview period, the Search API will become an official component of GitHub API v3. At that point, the new Search API will be stable and suitable for production use.

What about the old search API?

The legacy search API is still available. Many existing clients depend on it, and it is not changing in any way. While the new API offers much more functionality, the legacy search endpoints remain an official part of GitHub API v3.

Take it for a spin

We hope you’ll kick the tires and send us your feedback. Happy searching finding!

When Does My Rate Limit Reset?

Have you ever wondered when your rate limit will reset back to its maximum value? That information is now available in the new X-RateLimit-Reset response header.

$ curl -I https://api.github.com/orgs/octokit

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1372700873
...

The X-RateLimit-Reset header provides a Unix UTC timestamp, letting you know the exact time that your fresh new rate limit kicks in.

The reset timestamp is also available as part of the /rate_limit resource.

$ curl https://api.github.com/rate_limit

{
  "rate": {
    "limit": 60,
    "remaining": 42,
    "reset": 1372700873
  }
}

For more information on rate limits, be sure to check out the docs.

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

Feeds API

Today we’re releasing a new Feeds API, an easy way to list all the Atom resources available to the authenticated user.


curl -u defunkt https://api.github.com/feeds

{
  "timeline_url": "https://github.com/timeline",
  "user_url": "https://github.com/{user}",
  "current_user_public_url": "https://github.com/defunkt",
  "current_user_url": "https://github.com/defunkt.private?token=abc123",
  "current_user_actor_url": "https://github.com/defunkt.private.actor?token=abc123",
  "current_user_organization_url": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
  "_links": {
    "timeline": {
      "href": "https://github.com/timeline",
      "type": "application/atom+xml"
    },
    "user": {
      "href": "https://github.com/{user}",
      "type": "application/atom+xml"
    },
    "current_user_public": {
      "href": "https://github.com/defunkt",
      "type": "application/atom+xml"
    },
    "current_user": {
      "href": "https://github.com/defunkt.private?token=abc123",
      "type": "application/atom+xml"
    },
    "current_user_actor": {
      "href": "https://github.com/defunkt.private.actor?token=abc123",
      "type": "application/atom+xml"
    },
    "current_user_organization": {
      "href": "https://github.com/organizations/{org}/defunkt.private.atom?token=abc123",
      "type": "application/atom+xml"
    }
  }
}

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

Create, update, and delete individual files

We’re following in the footsteps of GitHub.com’s ability to edit and create files in your web browser. Starting today, the Repository Contents API will let you easily create, update, and even delete individual files.

Happy editing!

Repository Statistics

Today we’re happy to open our Repository Statistics API to everyone. We’re using repository statistics to power our graphs, but we can’t wait to see what others can do with this information.

Starting today, these resources are available to you:

Enjoy!

Improved Support for Submodules in the Repository Contents API

When you view a repository with a submodule on github.com, you get useful links and information for the submodule.

Repository Contents with Submodule

Today we’re making that data available in the Repository Contents API.

curl https://api.github.com/repos/jquery/jquery/contents/test/qunit

{
  "name": "qunit",
  "path": "test/qunit",
  "type": "submodule",
  "submodule_git_url": "git://github.com/jquery/qunit.git",
  "sha": "6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "size": 0,
  "url": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
  "git_url": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "html_url": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9",
  "_links": {
    "self": "https://api.github.com/repos/jquery/jquery/contents/test/qunit?ref=master",
    "git": "https://api.github.com/repos/jquery/qunit/git/trees/6ca3721222109997540bd6d9ccd396902e0ad2f9",
    "html": "https://github.com/jquery/qunit/tree/6ca3721222109997540bd6d9ccd396902e0ad2f9"
  }
}

If you have any questions or feedback, please drop us a line at [email protected].

Commit Statuses Now Available for Branches and Tags

  • April 30, 2013
  • foca

Last week we announced support for build statuses in the branches page. Now we are extending this to the API. The API endpoint for commit statuses has been extended to allow branch and tag names, as well as commit SHAs.

curl https://api.github.com/repos/rails/rails/statuses/3-2-stable

Enjoy.

Deprecating a Confusing Attribute in the Pull Request API

When you get the details for a Pull Request from the API, the response provides everything there is to know about that Pull Request. In addition to the useful information provided in the API response, the JSON also includes the merge_commit_sha attribute. This attribute is a frequent source of misunderstanding, and we aim to remove the confusion.

To help current API consumers, we’ve documented the attribute for improved understanding.

To protect future API consumers from this confusion, we have deprecated the merge_commit_sha attribute, and we will remove it in the next major version of the API.

As always, if you have any questions or feedback, please drop us a line at [email protected].

User Agent now mandatory

After an almost six week grace period, we’re now enforcing the User Agent header for all API requests. Most HTTP libraries (including cURL) set this header by default. If you’re experiencing an increase in 403 responses, be sure and check your code.

If you have any questions or feedback, please drop us a line at [email protected].

New Hookshot Changes

We are experimenting with changes to the “Hookshot” backend that powers service hooks. There were some significant networking changes with the new cluster, so there are some new IP whitelist rules for hooks:

  • 204.232.175.64/27
  • 192.30.252.0/22

These are in CIDR notation. They represent a significant range of GitHub addresses, meaning this should be the last IP change for a while. Once this cluster is activated and we shut the other cluster down, we will be removing the other entries.

We are currently testing the new backend with all repositories in the GitHub organization only, and expect to start testing it with user data next week.

This also means we should be able to start accepting GitHub Services pull requests very soon :)

Sortable Stars in Repository Starring API

As we announced on the GitHub blog, Stars now support sorting. The Repository Starring API now supports two new parameters when listing Stars: sort and direction.

curl https://api.github.com/users/defunkt/starred?sort=created&direction=asc

Enjoy.

Hookshot Load balancer

We had an issue with the Hookshot load balancer this morning, causing the majority of hooks to flow to a single node only. This lead to massive queue times. While fixing this, we’re putting the old Services backend in use.

This means the old IPs are back in use. Use this Help guide if you already removed them from your firewall.

Some Hookshot Issues

We turned Hookshot (our new GitHub Services backend) on yesterday. Things have been pretty smooth, with one issue: Hooks going to other EC2 nodes come from the private IP addresses of our nodes in the 10...* range.

If your web hook servers are on EC2 and are missing hooks from GitHub due to an IP restriction, we recommend the following:

  1. Remove the IP white list.
  2. Fall back to HTTPS and Basic Auth to restrict pushes to authorized senders only.

We’re currently working on solving this problem. Hit up [email protected] if you have any questions.

Upcoming Changes to GitHub Services

We are finishing up a new GitHub Services backend, dubbed “Hookshot”, to increase the speed and reliability of our delivered payloads. We are doing what we can to make this a seamless transition for everyone. However, there are a few notable changes.

  • There is a new Meta API endpoint listing the current public IPs that hooks originate from.

  • We’re removing the AMQP service from GitHub. It hasn’t worked in quite some time, and the code it uses doesn’t work in our background workers.

  • We’re also instituting a new guideline to improve the reliability and maintainability of services in the future. As of today, all new services must accept an unmodified payload over HTTP. Any service that does not will be rejected. To see an example of an acceptable service, check out Code Climate. Notice their service simply accepts HTTP POST from GitHub unmodified. For an example of a service that won’t be accepted after today, check out Campfire. It uses other Ruby gems and contains custom logic to transform the GitHub payload to Campfire messages. Existing hooks will keep working (don’t worry 37signals, we :heart: Campfire).

We’re making these changes because we want to focus on the reliability of the core Services backend for everyone. Maintaining custom logic and libraries for over 100 services is taking too much of this focus away.

User Agent mandatory from March 4th 2013

  • January 31, 2013
  • agh

Following on from our previous post about requiring requests to include a valid User Agent header we will soon be changing our API servers to return HTTP 403 to any clients not providing a valid User Agent header.

We will be making this change on Monday, March 4th 2013.

Setting this helps us identify requests from you, and get in touch with people who are using the API in a way which causes disruption to GitHub. Most HTTP libraries and tools like cURL already provide a valid header for you, and allow you to customize it, so this will not require many of our users to make any changes whatsoever.

If you have any questions or feedback, please drop us a line at [email protected].

New User scopes

We’ve added a few new user scopes for 3rd party applications that want very specific user functionality. The user:email scope gives apps read-only access to a user’s private email addresses. The user:follow scope lets a user follow and unfollow other users.

This should help keep applications from requiring the user scope, which can be potentially dangerous.

We also added a read-only endpoint to get a user’s public SSH keys.

GET https://api.github.com/users/technoweenie/keys

Diff and patch media types

Starting today, you can get .diff and .patch content directly from the API for the following resources:

Simply use the same resource URL and send either application/vnd.github.diff or application/vnd.github.patch in the Accept header:

curl -H "Accept: application/vnd.github.diff" https://api.github.com/repos/pengwynn/dotfiles/commits/aee60a4cd56fb4c6a50e60f17096fc40c0d4d72c

diff --git a/tmux/tmux.conf.symlink b/tmux/tmux.conf.symlink
index 1f599cb..abaf625 100755
--- a/tmux/tmux.conf.symlink
+++ b/tmux/tmux.conf.symlink
@@ -111,6 +111,7 @@ set-option -g base-index 1
 ## enable mouse
 set-option -g mouse-select-pane on
 set-option -g mouse-select-window on
+set-option -g mouse-resize-pane on
 set-window-option -g mode-keys vi
 set-window-option -g mode-mouse on
 # set-window-option -g monitor-activity off

Pagination for Organization Repository lists now paginates properly

  • December 9, 2012
  • rick

Improvements continue to the Organizations Repository listing endpoint. Today we’re improving pagination so that it works as documented. Now you can expect Link headers to navigate through the results space, regardless of what you send in the type parameter.

The docs for Organization Repositories queries are still here:

EDIT: Link headers are our preferred navigation technique.

Finding sources and fork repositories for organizations

  • December 8, 2012
  • rick

We’ve made a couple of changes today to the Organization repositories listing to bring it a bit closer to the functionality of the GitHub.com Organization repositories tab. We now let you retrieve repositories which are forks of another repo, as well as those repositories which are sources (not forks).

# Grab all fork Repositories for an Organization
curl "https://api.github.com/orgs/:org/repos?type=forks"

# Grab all source Repositories for an Organization
curl "https://api.github.com/orgs/:org/repos?type=sources"

Check out the docs for sorting and filtering options:

Create an OAuth authorization for an app

The Authorizations API is an easy way to create an OAuth authorization using Basic Auth. Just POST your desired scopes and optional note and you get a token back:

    curl -u pengwynn -d '{"scopes": ["user", "gist"]}' \
         https://api.github.com/authorizations

This call creates a token for the authenticating user tied to a special “API” OAuth application.

We now support creating tokens for your own OAuth application by passing your twenty character client_id and forty character client_secret as found in the settings page for your OAuth application.

    curl -u pengwynn -d '{ \
                          "scopes": ["user", "gist"], \
                          "client_id": "abcdeabcdeabcdeabcdeabcde" \
                          "client_secret": "abcdeabcdeabcdeabcdeabcdeabcdeabcdeabcdeabcde" \
                         }' \ '
            https://api.github.com/authorizations

No more implementing the web flow just to get a token tied to your app’s rate limit.

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 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/pengwynn/octokit

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 at [email protected].