mirror of
https://github.com/kennethreitz/python-github3.git
synced 2026-06-05 23:10:17 +00:00
site's up, no need to clone docs
This commit is contained in:
Kenneth Reitz
@@ -1,86 +0,0 @@
|
||||
## GitHub API v3
|
||||
|
||||
**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.
|
||||
|
||||
Blank fields are included as `null` instead of being omitted.
|
||||
|
||||
All timestamps are returned in ISO 8601 format:
|
||||
|
||||
YYYY-MM-DDTHH:MM:SSZ
|
||||
|
||||
### 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](http://develop.github.com).
|
||||
|
||||
### 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.json?page=2&per_page=100
|
||||
|
||||
### Rate Limiting
|
||||
|
||||
We limit requests to API v3 to 5000 per day. This is keyed off either your login, or your request IP. You can check the returned HTTP headers to see your current status:
|
||||
|
||||
$ curl -i https://api.github.com
|
||||
HTTP/1.1 200 OK
|
||||
Status: 200 OK
|
||||
X-RateLimit-Limit: 5000
|
||||
X-RateLimit-Remaining: 4966
|
||||
|
||||
You can file a [support issue](http://support.github.com/dashboard/queues/2386-api) to request white listed access for your application. We prefer sites that setup OAuth applications for their users.
|
||||
|
||||
### 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 responses always return 200, and are wrapped in meta
|
||||
objects containing the actual meta information:
|
||||
|
||||
$ curl https://api.github.com?callback=foo
|
||||
|
||||
foo({
|
||||
"data": {},
|
||||
"meta": {
|
||||
"status": 200,
|
||||
"pagination": {"page": 1, "per_page": 30},
|
||||
"rate": {"key": "IP ADDRESS", "remaining": 4999, "limit": 5000}
|
||||
}
|
||||
})
|
||||
|
||||
### Versions
|
||||
|
||||
Api V3 uses content negotiation to specify the expected output format.
|
||||
V3 is specified with this mime type:
|
||||
|
||||
application/vnd.github.v3+json
|
||||
|
||||
This allows us to upgrade the API if needed, and support multiple versions of the API in transition period. If you want to ensure your API usage works uninterrupted, you will want to specify this mime type in an Accept header:
|
||||
|
||||
curl -H "Accept: application/vnd.github.v3+json" https://api.github.com
|
||||
|
||||
Specifying `application/json` will assume the latest version of the API. Specifying an unknown version will result in a `406 Not Acceptable` error.
|
||||
|
||||
We don't plan to bump the API version unless absolutely necessary. Things like removing end points, renaming or removing object attributes, or removing resources completely will result in a new version. This should be extremely rare, however.
|
||||
@@ -1,15 +0,0 @@
|
||||
# Issue Comments API
|
||||
|
||||
## Get Comments for an Issue
|
||||
|
||||
### GET `/repos/:user/:repo/issues/:id/comments.json`
|
||||
|
||||
## Create a Comment for an Issue
|
||||
|
||||
### POST `/repos/:user/:repo/issues/:id/comments.json`
|
||||
|
||||
### Input
|
||||
|
||||
{
|
||||
body: String,
|
||||
}
|
||||
@@ -1,48 +0,0 @@
|
||||
# Issues API
|
||||
|
||||
## List issues for this Repository
|
||||
|
||||
### GET `/repos/:user/:repo/issues.json`
|
||||
|
||||
* `?milestone` = (Fixnum)
|
||||
* `?sort` = (String)
|
||||
* `?direction` = (String)
|
||||
* `?state` = open, closed, default: open
|
||||
* `?assignee` = (String)
|
||||
* `?mentioned` = (String)
|
||||
* `?labels` = (String)
|
||||
|
||||
|
||||
## Create an Issue
|
||||
|
||||
### POST `/repos/:user/:repo/issues.json`
|
||||
|
||||
### Input
|
||||
|
||||
{
|
||||
title: String,
|
||||
body: String,
|
||||
assignee: String,
|
||||
milestone: Fixnum,
|
||||
}
|
||||
|
||||
## Get a single Issue
|
||||
|
||||
### GET `/repos/:user/:repo/issues/:id.json`
|
||||
|
||||
## Edit an Issue
|
||||
|
||||
### PUT `/repos/:user/:repo/issues/:id.json`
|
||||
|
||||
### Input
|
||||
|
||||
{
|
||||
title: String,
|
||||
body: String,
|
||||
assignee: String,
|
||||
milestone: Fixnum,
|
||||
}
|
||||
|
||||
## Delete an Issue
|
||||
|
||||
### DELETE `/repos/:user/:repo/issues/:id.json`
|
||||
@@ -1,71 +0,0 @@
|
||||
# Labels API
|
||||
|
||||
## List all Labels for this Repository
|
||||
|
||||
### GET `/repos/:user/:repo/labels.json`
|
||||
|
||||
## Create a Label
|
||||
|
||||
### POST `/repos/:user/:repo/labels.json`
|
||||
|
||||
### Input
|
||||
|
||||
{
|
||||
name: String,
|
||||
color: String,
|
||||
}
|
||||
|
||||
## Get a single Label
|
||||
|
||||
### GET `/repos/:user/:repo/labels/:id.json`
|
||||
|
||||
## Update a Label
|
||||
|
||||
### PUT `/repos/:user/:repo/labels/:id.json`
|
||||
|
||||
### Input
|
||||
|
||||
{
|
||||
name: String,
|
||||
color: String,
|
||||
}
|
||||
|
||||
## Delete a label
|
||||
|
||||
### DELETE `/repos/:user/:repo/labels/:id.json`
|
||||
|
||||
## List labels on the Issue
|
||||
|
||||
### GET `/repos/:user/:repo/issues/:id/labels.json`
|
||||
|
||||
## Add a Label to an Issue
|
||||
|
||||
### POST `/repos/:user/:repo/issues/:id/labels.json`
|
||||
|
||||
### Input
|
||||
|
||||
[{
|
||||
name: String,
|
||||
}, ...]
|
||||
|
||||
## Remove a Label from an Issue
|
||||
|
||||
### DELETE `/repos/:user/:repo/issues/:id/labels/:id.json`
|
||||
|
||||
## Replace all Labels for an Issue
|
||||
|
||||
### PUT `/repos/:user/:repo/issues/:id/labels.json`
|
||||
|
||||
### Input
|
||||
|
||||
[{
|
||||
name: String,
|
||||
}, ...]
|
||||
|
||||
## Remove all Labels from an Issue
|
||||
|
||||
### DELETE `/repos/:user/:repo/issues/:id/labels.json`
|
||||
|
||||
## Get Labels for every Issue in a Milestone
|
||||
|
||||
### GET `/repos/:user/:repo/milestones/:id/labels.json`
|
||||
@@ -1,44 +0,0 @@
|
||||
# Milestones API
|
||||
|
||||
## List Milestones for an Issue
|
||||
|
||||
### GET `/repos/:user/:repo/milestones.json`
|
||||
|
||||
* `?sort` = (String)
|
||||
* `?direction` = (String)
|
||||
* `?state` = open, closed, default: open
|
||||
|
||||
|
||||
## Create a Milestone
|
||||
|
||||
### POST `/repos/:user/:repo/milestones.json`
|
||||
|
||||
### Input
|
||||
|
||||
{
|
||||
title: String,
|
||||
state: String,
|
||||
description: String,
|
||||
due_on: Time,
|
||||
}
|
||||
|
||||
## Get a single Milestone
|
||||
|
||||
### GET `/repos/:user/:repo/milestones/:id.json`
|
||||
|
||||
## Update a Milestone
|
||||
|
||||
### PUT `/repos/:user/:repo/milestones/:id.json`
|
||||
|
||||
### Input
|
||||
|
||||
{
|
||||
title: String,
|
||||
state: String,
|
||||
description: String,
|
||||
due_on: Time,
|
||||
}
|
||||
|
||||
## Delete a Milestone
|
||||
|
||||
### DELETE `/repos/:user/:repo/milestones/:id.json`
|
||||
Reference in New Issue
Block a user