Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

290 lines (207 sloc) 8.352 kB
title
GitHub API v3

API v3

This describes the resources that make up the official GitHub API v3. If you have any problems or requests please contact support.

Note: This API is in a beta state. Breaking changes may occur.

Schema

All API access is over HTTPS, and accessed from the api.github.com domain. All data is sent and received as JSON.

$ curl -i https://api.github.com

HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
Content-Length: 2

{}

Blank fields are included as null instead of being omitted.

All timestamps are returned in ISO 8601 format:

YYYY-MM-DDTHH:MM:SSZ

Client Errors

There are three possible types of client errors on API calls that receive request bodies:

  1. Sending invalid JSON will result in a 400 Bad Request response.

    HTTP/1.1 400 Bad Request
    Content-Length: 35
    
    {"message":"Problems parsing JSON"}
    
  2. Sending the wrong type of JSON values will result in a 400 Bad Request response.

    HTTP/1.1 400 Bad Request
    Content-Length: 40
    
    {"message":"Body should be a JSON Hash"}
    
  3. Sending invalid files will result in a 422 Unprocessable Entity response.

    HTTP/1.1 422 Unprocessable Entity
    Content-Length: 149
    
    {
      "message": "Validation Failed",
      "errors": [
        {
          "resource": "Issue",
          "field": "title",
          "code": "missing_field"
        }
      ]
    }
    

All error objects have resource and field properties so that your client can tell what the problem is. There's also an error code to let you know what is wrong with the field. These are the possible validation error codes:

missing : This means a resource does not exist.

missing_field : This means a required field on a resource has not been set.

invalid : This means the formatting of a field is invalid. The documentation for that resource should be able to give you more specific information.

already_exists : This means another resource has the same value as this field. This can happen in resources that must have some unique key (such as Label names).

If resources have custom validation errors, they will be documented with the resource.

HTTP Verbs

Where possible, API v3 strives to use appropriate HTTP verbs for each action.

HEAD : Can be issued against any resource to get just the HTTP header info.

GET : Used for retrieving resources.

POST : Used for creating resources, or performing custom actions (such as merging a pull request).

PATCH : Used for updating resources with partial JSON data. For instance, an Issue resource has title and body attributes. A PATCH request may accept one or more of the attributes to update the resource. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept POST requests.

PUT : Used for replacing resources or collections.

DELETE : Used for deleting resources.

Authentication

There are two ways to authenticate through GitHub API v3:

Basic Authentication:

$ curl -u "username:PASSWORD" https://api.github.com

OAuth2 Token (sent in a header):

$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com

OAuth2 Token (sent as a parameter):

$ curl https://api.github.com?access_token=OAUTH-TOKEN

Read more about OAuth2.

Pagination

Requests that return multiple items will be paginated to 30 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size up to 100 with the ?per_page parameter.

$ curl https://api.github.com/repos?page=2&per_page=100

The pagination info is included in the Link header:

Link: <https://api.github.com/repos?page=3&per_page=100>; rel="next",
  <https://api.github.com/repos?page=50&per_page=100>; rel="last"

Linebreak is included for readability.

The possible rel values are:

next : Shows the URL of the immediate next page of results.

last : Shows the URL of the last page of results.

first : Shows the URL of the first page of results.

prev : Shows the URL of the immediate previous page of results.

Rate Limiting

We limit requests to API v3 to 5000 per hour. This is keyed off either your login, your OAuth token, or request IP. You can check the returned HTTP headers of any API request to see your current status:

$ curl -i https://api.github.com/users/whatever

HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4966

You can file a support issue to request white listed access for your application. We prefer sites that setup OAuth applications for their users.

Cross Origin Resource Sharing

The API supports Cross Origin Resource Sharing (CORS) for AJAX requests. you can read the CORS W3C working draft, or this intro from the HTML 5 Security Guide.

Here's a sample request sent from a browser hitting http://some-site.com:

$ curl -i https://api.github.com -H "Origin: http://some-site.com" 
HTTP/1.1 302 Found

Any domain that is registered as an OAuth Application is accepted. Here's a sample request for a browser hitting Calendar About Nothing:

$ curl -i https://api.github.com -H "Origin: http://calendaraboutnothing.com" 
HTTP/1.1 302 Found
Access-Control-Allow-Origin: http://calendaraboutnothing.com
Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
Access-Control-Allow-Credentials: true

This is what the CORS preflight request looks like:

$ curl -i https://api.github.com -H "Origin: http://calendaraboutnothing.com" -X OPTIONS    
HTTP/1.1 204 No Content
Access-Control-Allow-Origin: http://calendaraboutnothing.com
Access-Control-Allow-Headers: Authorization, X-Requested-With
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
Access-Control-Max-Age: 86400
Access-Control-Allow-Credentials: true

JSON-P Callbacks

You can send a ?callback parameter to any GET call to have the results wrapped in a JSON function. This is typically used when browsers want to embed GitHub content in web pages by getting around cross domain issues. The response includes the same data output as the regular API, plus the relevant HTTP Header information.

$ curl https://api.github.com?callback=foo

foo({
  "meta": {
    "status": 200,
    "X-RateLimit-Limit": "5000",
    "X-RateLimit-Remaining": "4966",
    "Link": [ // pagination headers and other links
      ["https://api.github.com?page=2", {"rel": "next"}]
    ]
  },
  "data": {
    // the data
  }
})

You can write a javascript handler to process the callback like this:

function foo(response) {
  var meta = response.meta
  var data = response.data
  console.log(meta)
  console.log(data)
}

All of the headers are the same String value as the HTTP Headers with one notable exception: Link. Link headers are pre-parsed for you and come through as an array of [url, options] tuples.

A link that looks like this:

Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"

... will look like this in the Callback output:

<%= json "Link" => [ ["url1", {:rel => "next"}], ["url2", {:rel => "foo", :bar => "baz"}]] %>

Jump to Line
Something went wrong with that request. Please try again.