; rel="last"
+
+The [`Link` header][link-header] provides a way for a response to link to
+external resources, in this case additional pages of data. Since our call found
+more than thirty issues (the default page size), the API tells us where we can
+find the next page and the last page of results.
+
+### Creating an issue
+
+Now that we've seen how to paginate lists of issues, let's create an issue from
+the API.
+
+ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
+ -d '{ \
+ "title": "New logo", \
+ "body": "We should have one", \
+ "labels": ["design"] \
+ }' \
+ https://api.github.com/repos/pengwynn/api-sandbox/issues
+
+To create an issue, we need to be authenticated so we pass an
+OAuth token in the header. We pass the title, body, and labels in the JSON
+body to the `/issues` path underneath the repository in which we want to create
+the issue.
+
+ HTTP/1.1 201 Created
+ Location: https://api.github.com/repos/pengwynn/api-sandbox/issues/17
+ X-RateLimit-Limit: 5000
+
+ {
+ "pull_request": {
+ "patch_url": null,
+ "html_url": null,
+ "diff_url": null
+ },
+ "created_at": "2012-11-14T15:25:33Z",
+ "comments": 0,
+ "milestone": null,
+ "title": "New logo",
+ "body": "We should have one",
+ "user": {
+ "login": "pengwynn",
+ "gravatar_id": "7e19cd5486b5d6dc1ef90e671ba52ae0",
+ "avatar_url": "https://secure.gravatar.com/avatar/7e19cd5486b5d6dc1ef90e671ba52ae0?d=https://a248.e.akamai.net/assets.github.com%2Fimages%2Fgravatars%2Fgravatar-user-420.png",
+ "id": 865,
+ "url": "https://api.github.com/users/pengwynn"
+ },
+ "closed_at": null,
+ "updated_at": "2012-11-14T15:25:33Z",
+ "number": 17,
+ "closed_by": null,
+ "html_url": "https://github.com/pengwynn/api-sandbox/issues/17",
+ "labels": [
+ {
+ "color": "ededed",
+ "name": "design",
+ "url": "https://api.github.com/repos/pengwynn/api-sandbox/labels/design"
+ }
+ ],
+ "id": 8356941,
+ "assignee": null,
+ "state": "open",
+ "url": "https://api.github.com/repos/pengwynn/api-sandbox/issues/17"
+ }
+
+The response gives us a couple of pointers to the newly created issue, both in
+the `Location` response header and the `url` field of the JSON response.
+
+### Convert an issue to a Pull Request
+
+GitHub moves fast and the API tries to keep pace, but there are some things you
+can do with the API that you can't do on github.com. Using the API, you can
+turn an issue into a Pull Request. Let's convert the issue we just created
+
+
+ curl -i -H 'Authorization: token 5199831f4dd3b79e7c5b7e0ebe75d67aa66e79d4' \
+ -d '{ \
+ "issue": 17, \
+ "head": "new-feature", \
+ "base": "master" \
+ }' \
+ https://api.github.com/repos/pengwynn/api-sandbox/pulls
+
+Using this shorthand, the details for the pull request title and body are taken
+from the issue we provide.
+
+## Conditional requests
+
+A big part of being a good API citizen is respecting rate limits and caching
+information that does not change. The API supports [conditional
+requests][conditional-requests] and helps you do the right thing. Consider the
+first call we made to get @defunkt's profile:
+
+ curl -i https://api.github.com/users/defunkt
+
+In addition to the JSON body, take note of the HTTP status code of `200` and
+the `ETag` header:
+
+ HTTP/1.1 200 OK
+ ETag: "bfd85cbf23ac0b0c8a29bee02e7117c6"
+
+The ETag is a fingerprint of the response. If we pass that on subsequent calls,
+we can tell the API to give us the resource again, only if it has changed:
+
+ curl -i -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"' \
+ https://api.github.com/users/defunkt
+
+ HTTP/1.1 304 OK
+
+The `304` status indicates that the resource hasn't changed since the last time
+we asked for it and the response will contain no body. As a bonus, `304`
+responses don't count against your [rate limit][rate-limiting].
+
+
+
+[wrappers]: http://developer.github.com/v3/libraries/
+[curl]: http://curl.haxx.se/
+[media types]: http://developer.github.com/v3/media/
+[oauth]: http://developer.github.com/v3/oauth/
+[webflow]: http://developer.github.com/v3/oauth/#web-application-flow
+[authorizations api]: http://developer.github.com/v3/oauth/#oauth-authorizations-api
+[scopes]: http://developer.github.com/v3/oauth/#scopes
+[repos-api]: http://developer.github.com/v3/repos/
+[pages]: http://pages.github.com
+[nanoc]: http://nanoc.stoneship.org/
+[gitignore templates]: https://github.com/github/gitignore
+[issues-api]: http://developer.github.com/v3/issues/
+[link-header]: http://www.w3.org/wiki/LinkHeader
+[conditional-requests]: http://developer.github.com/v3/#conditional-requests
+[rate-limiting]: http://developer.github.com/v3/#rate-limiting
diff --git a/content/index.md b/content/index.md
index 8b90af8ce4..f5515ce829 100644
--- a/content/index.md
+++ b/content/index.md
@@ -24,28 +24,25 @@ to the actual date.
We consider the "beta" API unchangeable. [File a support issue](https://github.com/contact)
if you have problems.
-### Upcoming Version
-
- Accept: application/vnd.github.v3+json
-
-The API is expected to be finalized Real Soon Now.
-
#### Expected Changes
-* All `*_url` attributes move to a `_links` object. See [Pull
- Requests](/v3/pulls/#get-a-single-pull-request) for an example.
-* The `/repos/:owner/:repo/hooks/:id/test` action becomes
- `/repos/:owner/:repo/hooks/:id/tests`.
-* The `/gists/:id/fork` action becomes `/gists/:id/forks`.
-* Gist forks/history objects become separate API calls.
-* Gist files object is not returned on Gist listings.
-* Commit schema will change to be [more consistent](https://gist.github.com/3a2e5779588e21b0c0f3).
-* `master_branch` becomes `default_branch`.
-* `integrate_branch` on the [repo API](/v3/repos/#get) will no longer be
+These changes are _not_ implemented, just planned for the next major API version.
+
+* `[ ]` Standardize on existing `*_url` attributes for hypermedia. Remove all `_links`
+objects.
+* `[✓]` The '/repos/:owner/:repo/hooks/:id/test' action becomes
+ '/repos/:owner/:repo/hooks/:id/tests'.
+* `[✓]` The '/gists/:id/fork' action becomes '/gists/:id/forks'.
+* `[ ]` Gist forks/history objects become separate API calls.
+* `[ ]` Gist files object is not returned on Gist listings.
+* `[ ]` Commit schema will change to be [more consistent](https://gist.github.com/3a2e5779588e21b0c0f3).
+* `[ ]` `master_branch` becomes `default_branch`.
+* `[ ]` `integrate_branch` on the [repo API](/v3/repos/#get) will no longer be
returned.
-* Use the `private` attribute when creating a private repository,
+* `[ ]` Use the `private` attribute when creating a private repository,
instead of setting `public` to false.
-* User Emails come back as a hash instead of a string.
+* `[ ]` Use JSON to POST to the "repos/:owner/:repo/forks" endpoint, instead of a query string.
+* `[ ]` User Emails come back as a hash instead of a string.
{"email": "email@whatev.com", "state": "verified"}
diff --git a/content/v3.md b/content/v3.md
index 1b6f543b1a..8e7475b9a5 100644
--- a/content/v3.md
+++ b/content/v3.md
@@ -18,20 +18,23 @@ domain (or through `yourdomain.com/api/v3/` for enterprise). All data is
sent and received as JSON.
-$ curl -i https://api.github.com
+$ curl -i https://api.github.com/users/octocat/orgs
-HTTP/1.1 302 Found
-Server: nginx/1.0.12
-Date: Mon, 20 Feb 2012 11:15:49 GMT
-Content-Type: text/html;charset=utf-8
+HTTP/1.1 200 OK
+Server: nginx
+Date: Fri, 12 Oct 2012 23:33:14 GMT
+Content-Type: application/json; charset=utf-8
Connection: keep-alive
-Status: 302 Found
+Status: 200 OK
+ETag: "a00049ba79152d03380c34652f2cb612"
X-RateLimit-Limit: 5000
-ETag: "d41d8cd98f00b204e9800998ecf8427e"
-Location: http://developer.github.com
-X-RateLimit-Remaining: 4999
-Content-Length: 0
+X-GitHub-Media-Type: github.beta
+X-RateLimit-Remaining: 4987
+Content-Length: 5
+Cache-Control: max-age=0, private, must-revalidate
+X-Content-Type-Options: nosniff
+[]
Blank fields are included as `null` instead of being omitted.
@@ -120,8 +123,19 @@ already\_exists
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.
+If resources have custom validation errors, they will be documented with the resource.
+
+## HTTP Redirects
+
+API v3 uses HTTP redirection where appropriate. Clients should assume that any request may result in a redirection. Receiving an HTTP redirection is *not* an error and clients should follow that redirect. Redirect responses will have a `Location` header field which contains the URI of the resource to which the client should repeat the requests.
+
+301
+: Permanent redirection. The URI you used to make the request has be superseded by the one specified in the `Location` header field. This and all future requests to this resource should be directed the new URI.
+
+302, 307
+: Temporary redirection. The request should be repeated verbatim to the URI specified in the `Location` header field but clients should continue to use the original URI for future requests.
+
+Other redirection status codes may be used in accordance with the HTTP 1.1 spec.
## HTTP Verbs
@@ -154,21 +168,24 @@ DELETE
## Authentication
-There are two ways to authenticate through GitHub API v3:
+There are three ways to authenticate through GitHub API v3. Requests that
+require authentication will return 404, instead of 403, in some places. This
+is to prevent the accidental leakage of private repositories to unauthorized
+users.
-Basic Authentication:
+### Basic Authentication
$ curl -u "username" https://api.github.com
-OAuth2 Token (sent in a header):
+### OAuth2 Token (sent in a header)
$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
-OAuth2 Token (sent as a parameter):
+### OAuth2 Token (sent as a parameter)
$ curl https://api.github.com/?access_token=OAUTH-TOKEN
@@ -178,17 +195,47 @@ Read [more about OAuth2](/v3/oauth/). Note that OAuth2 tokens can be [acquired
programmatically](/v3/oauth/#create-a-new-authorization), for applications that
are not websites.
-Requests that require authentication will return 404, instead of 403, in some places.
-This is to prevent the accidental leakage of private repositories to unauthorized
-users.
+### OAuth2 Key/Secret
+
+
+$ curl https://api.github.com/users/whatever?client_id=xxxx&client_secret=yyyy
+
+
+This should only be used in server to server scenarios. Don't leak your
+OAuth application's client secret to your users. Read [more about
+unauthenticated rate limiting](#unauthenticated-rate-limited-requests).
+
+## Hypermedia
+
+All resources may have one or more `*_url` properties linking to other
+resources. These are meant to provide explicit URLs so that proper API clients
+don't need to construct URLs on their own. It is highly recommended that API
+clients use these. Doing so will make future upgrades of the API easier for
+developers. All URLs are expected to be proper [RFC 6570][rfc] URI templates.
+
+You can then expand these templates using something like the [`uri_template`][uri]
+gem:
+
+ >> tmpl = URITemplate.new('/notifications{?since,all,participating}')
+ >> tmpl.expand
+ => "/notifications"
+
+ >> tmpl.expand :all => 1
+ => "/notifications?all=1"
+
+ >> tmpl.expand :all => 1, :participating => 1
+ => "/notifications?all=1&participating=1"
+
+[rfc]: http://tools.ietf.org/html/rfc6570
+[uri]: https://github.com/hannesg/uri_template
## Pagination
Requests that return multiple items will be paginated to 30 items by
-default. You can specify further pages with the `?page` parameter. For some
+default. You can specify further pages with the `?page` parameter. For some
resources, you can also set a custom page size up to 100 with the `?per_page` parameter.
Note that for technical reasons not all endpoints respect the `?per_page` parameter,
-see [events](http://developer.github.com/v3/events/) for example.
+see [events](http://developer.github.com/v3/activity/events/) for example.
$ curl https://api.github.com/user/repos?page=2&per_page=100
@@ -222,9 +269,10 @@ The possible `rel` values are:
## 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:
+We limit requests to 60 per hour for unauthenticated requests. For requests
+using Basic Authentication or OAuth, we limit requests to 5,000
+per hour. You can check the returned HTTP headers of any API request to see
+your current status:
$ curl -i https://api.github.com/users/whatever
@@ -264,11 +312,17 @@ X-RateLimit-Remaining: 11966
This method should only be used for server-to-server calls. You should never
share your client secret with anyone or include it in client-side browser code.
-Please [contact us](https://github.com/contact) to request white listed access
-for your application. We prefer sites that setup OAuth applications for their
- users.
+Please [contact us](https://github.com/contact) to request a higher rate limit
+for your OAuth application.
+
+## User Agent Required
-## Conditional Requests
+All API requests are encouraged to send a valid User Agent string. This is
+usually the HTTP client that you are using. If you are hitting the API without
+authentication, we ask that you add some kind of identification to the UA. This
+is so we can contact you if there are problems.
+
+## Conditional requests
Most responses return `Last-Modified` and `Etag` headers. You can use the values
of these headers to make subsequent requests to those resources using the
@@ -390,3 +444,4 @@ A link that looks like this:
["url1", {:rel => "next"}],
["url2", {:rel => "foo", :bar => "baz"}]] %>
+
diff --git a/content/v3/activity.md b/content/v3/activity.md
new file mode 100644
index 0000000000..b58eca92d7
--- /dev/null
+++ b/content/v3/activity.md
@@ -0,0 +1,28 @@
+---
+title: Activity | GitHub API
+---
+
+Serving up the 'social' in Social Coding™, the Activity APIs provide access to
+notifications, subscriptions, and timelines.
+
+## Notifications
+
+Notifications of new comments are delivered to users. The Notifications API
+lets you view these notifications, and mark them as read.
+
+## Starring
+
+Repository Starring is a feature that lets users bookmark repositories. Stars
+are shown next to repositories to show an approximate level of interest. Stars
+have no effect on notifications or the activity feed.
+
+## Watching
+
+Watching a Repository registers the user to receive notifications on new
+discussions, as well as events in the user's activity feed.
+
+## Events
+
+This is a read-only API of the events that power the various activity streams
+on GitHub.
+
diff --git a/content/v3/events.md b/content/v3/activity/events.md
similarity index 68%
rename from content/v3/events.md
rename to content/v3/activity/events.md
index caca786f02..f9436ea722 100644
--- a/content/v3/events.md
+++ b/content/v3/activity/events.md
@@ -10,6 +10,23 @@ various activity streams on the site.
* TOC
{:toc}
+Events are optimized for polling with the "ETag" header. If no new events have
+been triggered, you will see a "304 Not Modified" response, and your current
+rate limit will be untouched. There is also an "X-Poll-Interval" header that
+specifies how often (in seconds) you are allowed to poll. In times of high
+server load, the time may increase. Please obey the header.
+
+ $ curl -I https://api.github.com/users/tater/events
+ HTTP/1.1 200 OK
+ X-Poll-Interval: 60
+ ETag: "a18c3bded88eb5dbb5c849a489412bf3"
+
+ # The quotes around the ETag value are important
+ $ curl -I https://api.github.com/users/tater/events \
+ -H 'If-None-Match: "a18c3bded88eb5dbb5c849a489412bf3"'
+ HTTP/1.1 304 Not Modified
+ X-Poll-Interval: 60
+
Events support [pagination](/v3/#pagination),
however the `per_page` option is unsupported. The fixed page size is 30 items.
Fetching up to ten pages is supported, for a total of 300 events.
diff --git a/content/v3/events/types.md b/content/v3/activity/events/types.md
similarity index 97%
rename from content/v3/events/types.md
rename to content/v3/activity/events/types.md
index 4cc587e130..fab4f8b09c 100644
--- a/content/v3/events/types.md
+++ b/content/v3/activity/events/types.md
@@ -225,6 +225,10 @@ commits[][author][email]
commits[][url]
: **url** - Points to the commit API resource.
+commits[][distinct]
+: **boolean** - Whether this commit is distinct from any that have been pushed
+before.
+
## TeamAddEvent
Hook name: `team_add`
diff --git a/content/v3/activity/notifications.md b/content/v3/activity/notifications.md
new file mode 100644
index 0000000000..a554d69725
--- /dev/null
+++ b/content/v3/activity/notifications.md
@@ -0,0 +1,218 @@
+---
+title: Notifications | GitHub API
+---
+
+# Notifications API
+
+* TOC
+{:toc}
+
+GitHub Notifications are powered by [watched repositories](/v3/repos/watching/).
+Users receive notifications for discussions in repositories they watch
+including:
+
+* Issues and their comments
+* Pull Requests and their comments
+* Comments on any commits
+
+Notifications are also sent for discussions in unwatched repositories when the
+user is involved including:
+
+* **@mentions**
+* Issue assignments
+* Commits the user authors or commits
+* Any discussion in which the user actively participates
+
+All Notification API calls require the "notifications" or
+"repo API scopes. Doing this will give read-only access to
+some Issue/Commit content. You will still need the "repo" scope to access
+Issues and Commits from their respective endpoints.
+
+Notifications come back as "threads". A Thread contains information about the
+current discussion of an Issue/PullRequest/Commit.
+
+Notifications are optimized for polling with the "Last-Modified" header. If
+there are no new notifications, you will see a "304 Not Modified" response,
+leaving your current rate limit untouched. There is an "X-Poll-Interval"
+header that specifies how often (in seconds) you are allowed to poll. In times
+of high server load, the time may increase. Please obey the header.
+
+ # 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
+
+## List your notifications
+
+List all notifications for the current user, grouped by repository.
+
+ GET /notifications
+
+### Parameters
+
+all
+: _Optional_ **boolean** `true` to show notifications marked as read.
+
+participating
+: _Optional_ **boolean** `true` to show only notifications in which the user is
+directly participating or mentioned.
+
+since
+: _Optional_ **time** filters out any notifications updated before the given
+time. The time should be passed in as UTC in the ISO 8601 format:
+`YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".
+
+### Response
+
+<%= headers 200 %>
+<%= json(:thread) { |h| [h] } %>
+
+## List your notifications in a repository
+
+List all notifications for the current user.
+
+ GET /repos/:owner/:repo/notifications
+
+### Parameters
+
+all
+: _Optional_ **boolean** `true` to show notifications marked as read.
+
+participating
+: _Optional_ **boolean** `true` to show only notifications in which the user is
+directly participating or mentioned.
+
+since
+: _Optional_ **time** filters out any notifications updated before the given
+time. The time should be passed in as UTC in the ISO 8601 format:
+`YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".
+
+### Response
+
+<%= headers 200 %>
+<%= json(:thread) { |h| [h] } %>
+
+## Mark as read
+
+Marking a notification as "read" removes it from the [default view
+on GitHub.com](https://github.com/notifications).
+
+ PUT /notifications
+
+### Input
+
+unread
+: **Boolean** Changes the unread status of the threads.
+
+read
+: **Boolean** Inverse of "unread".
+
+last_read_at
+: _Optional_ **Time** Describes the last point that notifications were checked. Anything
+updated since this time will not be updated. Default: Now. Expected in ISO
+8601 format: `YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".
+
+### Response
+
+<%= headers 205 %>
+
+## Mark notifications as read in a repository
+
+Marking all notifications in a repository as "read" removes them
+from the [default view on GitHub.com](https://github.com/notifications).
+
+ PUT /repos/:owner/:repo/notifications
+
+### Input
+
+unread
+: **Boolean** Changes the unread status of the threads.
+
+read
+: **Boolean** Inverse of "unread".
+
+last_read_at
+: _Optional_ **Time** Describes the last point that notifications were checked. Anything
+updated since this time will not be updated. Default: Now. Expected in ISO
+8601 format: `YYYY-MM-DDTHH:MM:SSZ`. Example: "2012-10-09T23:39:01Z".
+
+### Response
+
+<%= headers 205 %>
+
+## View a single thread
+
+ GET /notifications/threads/:id
+
+### Response
+
+<%= headers 200 %>
+<%= json(:thread) %>
+
+## Mark a thread as read
+
+ PATCH /notifications/threads/:id
+
+### Input
+
+unread
+: **Boolean** Changes the unread status of the threads.
+
+read
+: **Boolean** Inverse of "unread".
+
+### Response
+
+<%= headers 205 %>
+
+## Get a Thread Subscription
+
+This checks to see if the current user is subscribed to a thread. You can also
+[get a Repository subscription](/v3/activity/watching/#get-a-repository-subscription).
+
+ GET /notifications/threads/1/subscription
+
+### Response
+
+<%= headers 200 %>
+<%= json :subscription %>
+
+## Set a Thread Subscription
+
+This lets you subscribe to a thread, or ignore it. Subscribing to a thread
+is unnecessary if the user is already subscribed to the repository. Ignoring
+a thread will mute all future notifications (until you comment or get
+@mentioned).
+
+ PUT /notifications/threads/1/subscription
+
+### Input
+
+subscribed
+: **boolean** Determines if notifications should be received from this
+thread.
+
+ignored
+: **boolean** Determines if all notifications should be blocked from this
+thread.
+
+### Response
+
+<%= headers 200 %>
+<%= json :subscription %>
+
+## Delete a Thread Subscription
+
+ DELETE /notifications/threads/1/subscription
+
+### Response
+
+<%= headers 204 %>
+
diff --git a/content/v3/activity/settings.md b/content/v3/activity/settings.md
new file mode 100644
index 0000000000..3244ed67f1
--- /dev/null
+++ b/content/v3/activity/settings.md
@@ -0,0 +1,79 @@
+---
+title: Notification Settings | GitHub API
+---
+
+# Notification Settings API
+
+This API is not implemented. This documentation is a placeholder for when it
+is ready for public consumption.
+
+## View Settings
+
+ GET /notifications/settings
+
+## Update Settings
+
+Update the notification settings for the authenticated user.
+
+ PATCH /notifications/settings
+
+### Parameters
+
+participating.email
+: _Optional_ **boolean** `true` to receive participating notifications via
+email.
+
+participating.web
+: _Optional_ **boolean** `true` to receive participating notifications via
+web.
+
+watching.email
+: _Optional_ **boolean** `true` to receive watching notifications via
+email.
+
+watching.web
+: _Optional_ **boolean** `true` to receive watching notifications via
+web.
+
+<%= json \
+ :participating => {:email => true, :web => false},
+ :watching => {:email => true, :web => false} %>
+
+## Get notification email settings
+
+ GET /notifications/emails
+
+## Get the global email settings
+
+ GET /notifications/global/emails
+
+## Get notification email settings for an organization
+
+ GET /notifications/organization/:org/emails
+
+## Update email settings
+
+ PATCH /notifications/emails
+
+## Update global email settings
+
+ PUT /notifications/global/emails
+
+### Parameters
+
+email
+: _Required_ **string** Email address to which to send notifications to the
+authenticated user for discussions related to projects for this organization.
+
+## Update Organization email settings
+
+Update the notification settings for the authenticated user.
+
+ PUT /notifications/organization/:org/emails
+
+### Parameters
+
+email
+: _Required_ **string** Email address to which to send notifications to the
+authenticated user for discussions related to projects for this organization.
+
diff --git a/content/v3/repos/starring.md b/content/v3/activity/starring.md
similarity index 98%
rename from content/v3/repos/starring.md
rename to content/v3/activity/starring.md
index 38cb24c383..ad6746a982 100644
--- a/content/v3/repos/starring.md
+++ b/content/v3/activity/starring.md
@@ -10,7 +10,7 @@ title: Repository Starring | GitHub API
Repository Starring is a feature that lets users bookmark repositories. Stars
are shown next to repositories to show an approximate level of interest. Stars
have no effect on notifications or the activity feed. For that, see [Repository
-Watching](/v3/repos/watching).
+Watching](/v3/activity/watching).
We recently [changed the way watching
works](https://github.com/blog/1204-notifications-stars) on GitHub. Many 3rd
diff --git a/content/v3/repos/watching.md b/content/v3/activity/watching.md
similarity index 62%
rename from content/v3/repos/watching.md
rename to content/v3/activity/watching.md
index da7e3985cb..072242a113 100644
--- a/content/v3/repos/watching.md
+++ b/content/v3/activity/watching.md
@@ -7,9 +7,9 @@ title: Repository Watching | GitHub API
* TOC
{:toc}
-Watching a Repository registers the user to receive notificactions on new
+Watching a Repository registers the user to receive notifications on new
discussions, as well as events in the user's activity feed. See [Repository
-Starring](/v3/repos/starring) for simple repository bookmarks.
+Starring](/v3/activity/starring) for simple repository bookmarks.
We recently [changed the way watching
works](https://github.com/blog/1204-notifications-stars) on GitHub. Until 3rd
@@ -41,7 +41,43 @@ List repositories being watched by the authenticated user.
<%= headers 200, :pagination => true %>
<%= json(:repo) { |h| [h] } %>
-## Check if you are watching a repository
+## Get a Repository Subscription
+
+ GET /repos/:owner/:repo/subscription
+
+### Response
+
+<%= headers 200 %>
+<%= json :repo_subscription %>
+
+## Set a Repository Subscription
+
+ PUT /repos/:owner/:repo/subscription
+
+### Input
+
+subscribed
+: **boolean** Determines if notifications should be received from this
+repository.
+
+ignored
+: **boolean** Determines if all notifications should be blocked from this
+repository.
+
+### Response
+
+<%= headers 200 %>
+<%= json :repo_subscription %>
+
+## Delete a Repository Subscription
+
+ DELETE /repos/:owner/:repo/subscription
+
+### Response
+
+<%= headers 204 %>
+
+## Check if you are watching a repository (LEGACY)
Requires for the user to be authenticated.
@@ -55,7 +91,7 @@ Requires for the user to be authenticated.
<%= headers 404 %>
-## Watch a repository
+## Watch a repository (LEGACY)
Requires for the user to be authenticated.
@@ -65,7 +101,7 @@ Requires for the user to be authenticated.
<%= headers 204 %>
-## Stop watching a repository
+## Stop watching a repository (LEGACY)
Requires for the user to be authenticated.
diff --git a/content/v3/gists.md b/content/v3/gists.md
index 531be69dc1..6b61cb7f96 100644
--- a/content/v3/gists.md
+++ b/content/v3/gists.md
@@ -34,6 +34,12 @@ List the authenticated user's starred gists:
GET /gists/starred
+### Parameters
+
+since
+: _Optional_ **string** of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+Only gists updated at or after this time are returned.
+
### Response
<%= headers 200, :pagination => true %>
@@ -76,6 +82,9 @@ content
}
%>
+_Note:_ Don't name your files "gistfile" with a numerical suffix. This is the
+format of the automatic naming scheme that Gist uses internally.
+
### Response
<%= headers 201, :Location => "https://api.github.com/gists/1" %>
@@ -149,7 +158,9 @@ including the filename with a null hash.
## Fork a gist
- POST /gists/:id/fork
+ POST /gists/:id/forks
+
+**Note**: Previously `/gists/:id/fork`
### Response
diff --git a/content/v3/gists/comments.md b/content/v3/gists/comments.md
index 4f6dc6154d..c3014eda8a 100644
--- a/content/v3/gists/comments.md
+++ b/content/v3/gists/comments.md
@@ -7,8 +7,8 @@ title: Gist Comments | GitHub API
* TOC
{:toc}
-Gist Comments leverage [these](#custom-mime-types) custom mime types.
-You can read more about the use of mime types in the API
+Gist Comments leverage [these custom media types](#custom-media-types).
+You can read more about the use of media types in the API
[here](/v3/media/).
## List comments on a gist
@@ -22,7 +22,7 @@ You can read more about the use of mime types in the API
## Get a single comment
- GET /gists/comments/:id
+ GET /gists/:gist_id/comments/:id
### Response
@@ -48,7 +48,7 @@ body
## Edit a comment
- PATCH /gists/comments/:id
+ PATCH /gists/:gist_id/comments/:id
### Input
@@ -64,16 +64,16 @@ body
## Delete a comment
- DELETE /gists/comments/:id
+ DELETE /gists/:gist_id/comments/:id
### Response
<%= headers 204 %>
-## Custom Mime Types
+## Custom media types
-These are the supported mime types for gist comments. You can read more about the
-use of mime types in the API [here](/v3/media/).
+These are the supported media types for gist comments. You can read more about the
+use of media types in the API [here](/v3/media/).
application/vnd.github.VERSION.raw+json
application/vnd.github.VERSION.text+json
diff --git a/content/v3/git/blobs.md b/content/v3/git/blobs.md
index ad4b1d4753..a542ad81c0 100644
--- a/content/v3/git/blobs.md
+++ b/content/v3/git/blobs.md
@@ -12,8 +12,8 @@ for the blob API takes an encoding parameter that can be either `utf-8`
or `base64`. If your data cannot be losslessly sent as a UTF-8 string,
you can base64 encode it.
-Blobs leverage [these](#custom-mime-types) custom mime types. You can
-read more about the use of mime types in the API [here](/v3/media/).
+Blobs leverage [these custom media types](#custom-media-types). You can
+read more about the use of media types in the API [here](/v3/media/).
## Get a Blob
@@ -38,10 +38,10 @@ read more about the use of mime types in the API [here](/v3/media/).
:Location => "https://api.github.com/git/:owner/:repo/blob/:sha" %>
<%= json :sha => "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15" %>
-## Custom Mime Types
+## Custom media types
-These are the supported mime types for blobs. You can read more about the
-use of mime types in the API [here](/v3/media/).
+These are the supported media types for blobs. You can read more about the
+use of media types in the API [here](/v3/media/).
application/json
application/vnd.github.VERSION.raw
diff --git a/content/v3/git/commits.md b/content/v3/git/commits.md
index b2dfd6f495..31aeefe408 100644
--- a/content/v3/git/commits.md
+++ b/content/v3/git/commits.md
@@ -38,7 +38,7 @@ for a merge commit, an array of more than one should be provided.
The `committer` section is optional and will be filled with the `author`
data if omitted. If the `author` section is omitted, it will be filled
-in with the authenticated users information and the current date.
+in with the authenticated user's information and the current date.
author.name
diff --git a/content/v3/gitignore.md b/content/v3/gitignore.md
new file mode 100644
index 0000000000..ee9067c09f
--- /dev/null
+++ b/content/v3/gitignore.md
@@ -0,0 +1,62 @@
+---
+title: Gitignore templates | GitHub API
+---
+
+# Gitignore Templates API
+
+* TOC
+{:toc}
+
+When you create a new GitHub repository via the API, you can specify a
+[.gitignore template][what-is] to apply to the repository upon creation. The
+.gitignore Templates API lists and fetches templates from the [GitHub .gitignore repository][templates-repo].
+
+## Listing available templates
+
+List all templates available to pass as an option when [creating a repository][create-repo].
+
+ GET /gitignore/templates
+
+### Response
+
+<%= headers 200 %>
+<%= json(:templates) %>
+
+## Get a single template
+
+The API also allows fetching the source of a single template.
+
+ GET /gitignore/templates/C
+
+### Response
+
+<%= headers 200 %>
+<%= json(:template) %>
+
+Use the raw [media type][media-type] to get the raw contents.
+
+<%= headers 200 %>
+
+# Object files
+*.o
+
+# Libraries
+*.lib
+*.a
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+
+
+[what-is]: https://help.github.com/articles/ignoring-files
+[templates-repo]: https://github.com/github/gitignore
+[create-repo]: /v3/repos/#create
+[media-type]: /v3/media/
diff --git a/content/v3/issues.md b/content/v3/issues.md
index c918ecd0dd..c0a6fd4320 100644
--- a/content/v3/issues.md
+++ b/content/v3/issues.md
@@ -7,8 +7,8 @@ title: Issues | GitHub API
* TOC
{:toc}
-Issues leverage [these](#custom-mime-types) custom mime types. You can
-read more about the use of mime types in the API [here](/v3/media/).
+Issues leverage [these custom media types](#custom-media-types). You can
+read more about the use of media types in the API [here](/v3/media/).
## List issues
@@ -92,7 +92,7 @@ direction
: `asc` or `desc`, default: `desc`.
since
-: _Optional_ **string** of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+: _Optional_ **String** of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
### Response
@@ -187,10 +187,10 @@ Issue. Send an empty array (`[]`) to clear all Labels from the Issue.
<%= headers 200 %>
<%= json :issue %>
-## Custom Mime Types
+## Custom media types
-These are the supported mime types for issues. You can read more about the
-use of mime types in the API [here](/v3/media/).
+These are the supported media types for issues. You can read more about the
+use of media types in the API [here](/v3/media/).
application/vnd.github.VERSION.raw+json
application/vnd.github.VERSION.text+json
diff --git a/content/v3/issues/comments.md b/content/v3/issues/comments.md
index dc762e6a3b..222e755519 100644
--- a/content/v3/issues/comments.md
+++ b/content/v3/issues/comments.md
@@ -10,8 +10,8 @@ title: Issue Comments | GitHub API
The Issue Comments API supports listing, viewing, editing, and creating
comments on issues and pull requests.
-Issue Comments leverage [these](#custom-mime-types) custom mime types.
-You can read more about the use of mime types in the API
+Issue Comments leverage [these custom media types](#custom-media-types).
+You can read more about the use of media types in the API
[here](/v3/media/).
## List comments on an issue
@@ -23,6 +23,28 @@ You can read more about the use of mime types in the API
<%= headers 200, :pagination => true %>
<%= json(:issue_comment) { |h| [h] } %>
+## List comments in a repository
+
+ GET /repos/:owner/:repo/issues/comments
+
+By default, Issue Comments are ordered by ascending ID.
+
+### Parameters
+
+sort
+: _Optional_ **String** `created` or `updated`
+
+direction
+: _Optional_ **String** `asc` or `desc`. Ignored without `sort` parameter.
+
+since
+: _Optional_ **String** of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+
+### Response
+
+<%= headers 200 %>
+<%= json(:pull_comment) { |h| [h] } %>
+
## Get a single comment
GET /repos/:owner/:repo/issues/comments/:id
@@ -74,10 +96,10 @@ body
<%= headers 204 %>
-## Custom Mime Types
+## Custom media types
-These are the supported mime types for issue comments. You can read more
-about the use of mime types in the API [here](/v3/media/).
+These are the supported media types for issue comments. You can read more
+about the use of media types in the API [here](/v3/media/).
application/vnd.github.VERSION.raw+json
application/vnd.github.VERSION.text+json
diff --git a/content/v3/libraries.md b/content/v3/libraries.md
index ac5d107db2..1d693d9f4f 100644
--- a/content/v3/libraries.md
+++ b/content/v3/libraries.md
@@ -53,10 +53,12 @@ GitHub v3 API. Builds are available in [Maven Central](http://search.maven.org/
* [Node-GitHub][ajaxorg-node-github]
* [NodeJS GitHub library][octonode]
* [gh3 client-side API v3 wrapper][gh3]
+* [GitHub.js wrapper around the Github API][github]
[ajaxorg-node-github]: https://github.com/ajaxorg/node-github
[octonode]: https://github.com/pksunkara/octonode
[gh3]: https://github.com/k33g/gh3
+[github]: https://github.com/michael/github
## Objective-C
@@ -92,6 +94,7 @@ GitHub v3 API. Builds are available in [Maven Central](http://search.maven.org/
* [github3.py][github3py]
* [sanction][sanction]
* [agithub][agithub]
+* [githubpy][githubpy]
[jacquev6_pygithub]: https://github.com/jacquev6/PyGithub
[pygithub3-api]: https://github.com/copitux/python-github3
@@ -99,6 +102,7 @@ GitHub v3 API. Builds are available in [Maven Central](http://search.maven.org/
[github3py]: https://github.com/sigmavirus24/github3.py
[sanction]: https://github.com/demianbrecht/sanction
[agithub]: https://github.com/jpaugh64/agithub "Agnostic Github"
+[githubpy]: https://github.com/michaelliao/githubpy
## Ruby
diff --git a/content/v3/media.md b/content/v3/media.md
index 4cd96a86c2..e228b16d76 100644
--- a/content/v3/media.md
+++ b/content/v3/media.md
@@ -101,4 +101,20 @@ encoded string. This is the default if nothing is passed.
Return the raw blob data.
+## Commits, Commit comparison, and Pull Requests
+
+The Commit, Commit Comparison, and Pull Request resources support
+[diff][git-diff] and [patch][git-patch] formats:
+
+### diff
+
+ application/vnd.github.VERSION.diff
+
+### patch
+
+ application/vnd.github.VERSION.patch
+
+
[gfm]:http://github.github.com/github-flavored-markdown/
+[git-diff]: http://git-scm.com/docs/git-diff
+[git-patch]: http://git-scm.com/docs/git-format-patch
diff --git a/content/v3/oauth.md b/content/v3/oauth.md
index e572d007db..5992164fb3 100644
--- a/content/v3/oauth.md
+++ b/content/v3/oauth.md
@@ -1,7 +1,3 @@
----
-title: OAuth | GitHub API
----
-
# OAuth
* TOC
@@ -101,7 +97,7 @@ The access token allows you to make requests to the API on a behalf of a user.
## Non-Web Application Flow
Use basic authentication to create an OAuth2 token using the [interface
-below](/v3/oauth#create-a-new-authorization). With this technique, a username
+below](/v3/oauth/#create-a-new-authorization). With this technique, a username
and password need not be stored permanently, and the user can revoke access at
any time.
@@ -122,11 +118,15 @@ host.
## Scopes
-Scopes let you specify exactly what type of access you need. This will
-be displayed to the user on the authorize form.
+Scopes let you specify exactly what type of access you need. Scopes _limit_
+access for OAuth tokens. They do not grant any additional permission beyond
+that which the user already has.
+
+For the web flow, requested scopes be displayed to the user on the authorize
+form.
Check headers to see what OAuth scopes you have, and what the API action
-accept.
+accepts.
$ curl -H "Authorization: bearer TOKEN" https://api.github.com/users/technoweenie -I
HTTP/1.1 200 OK
@@ -156,6 +156,9 @@ include access to code - use `repo` for that.
delete\_repo
: Delete access to adminable repositories.
+notifications
+: Read access to a user's notifications. `repo` is accepted too.
+
gist
: write access to gists.
@@ -191,8 +194,11 @@ access your own tokens, and only through Basic Authentication.
## Create a new authorization
-Note: Authorizations created from the API will show up in the GitHub API
-app.
+If you need a small number of tokens, implementing the [web flow](#web-application-flow)
+can be cumbersome. Instead, tokens can be created using the Authorizations API using
+Basic Authentication. To create tokens for a particular OAuth application, you
+must provide its client ID and secret, found on the OAuth application settings
+page, linked from your [OAuth applications listing on GitHub][app-listing].
POST /authorizations
@@ -207,6 +213,14 @@ note
note_url
: _Optional_ **string** - A URL to remind you what app the OAuth token is for.
+client_id
+: _Optional_ **String** - The 20 character OAuth app client key for which to create the
+token.
+
+client_secret
+: _Optional_ **String** - The 40 character OAuth app client secret for which to create the
+token.
+
<%= json :scopes => ["public_repo"], :note => 'admin script' %>
### Response
@@ -256,6 +270,7 @@ You can only send one of these scope keys at a time.
## More Information
+
It can be a little tricky to get started with OAuth. Here are a few
links that might be of help:
@@ -267,3 +282,5 @@ links that might be of help:
* [Ruby OmniAuth example](http://github.com/intridea/omniauth)
* [Ruby Sinatra extension](http://github.com/atmos/sinatra_auth_github)
* [Ruby Warden strategy](http://github.com/atmos/warden-github)
+
+[app-listing]: https://github.com/settings/applications
diff --git a/content/v3/orgs/members.md b/content/v3/orgs/members.md
index 78db8bd8da..f766de76a6 100644
--- a/content/v3/orgs/members.md
+++ b/content/v3/orgs/members.md
@@ -7,12 +7,10 @@ title: Organization Members | GitHub API
* TOC
{:toc}
-## List members
+## Members list
List all users who are members of an organization. A member is a user
-that belongs to at least 1 team in the organization. If the authenticated user is
-also a member of this organization then both concealed and public
-members will be returned. Otherwise only public members are returned.
+that belongs to at least 1 team in the organization. If the authenticated user is also a member of this organization then both concealed and public members will be returned. If the requester is not a member of the organization the query will be redirected to the [public members list](#public-members-list).
GET /orgs/:org/members
@@ -21,18 +19,32 @@ members will be returned. Otherwise only public members are returned.
<%= headers 200 %>
<%= json(:user) { |h| [h] } %>
-## Get member
+### Response if requester is not an organization member
+
+<%= headers 302, "Location" => "https://api.github.com/orgs/github/public_members" %>
+
+## Check membership
+
+Check if a user is, publicly or privately, a member of the organization.
GET /orgs/:org/members/:user
-### Response if user is a member
+### Response if requester is an organization member and user is a member
<%= headers 204 %>
-### Response if user is not a member
+### Response if requester is an organization member and user is not a member
<%= headers 404 %>
+### Response if requester is not an organization member and is inquiring about themselves
+
+<%= headers 404 %>
+
+### Response if requester is not an organization member
+
+<%= headers 302, :Location => "https://api.github.com/orgs/github/public_members/pezra" %>
+
## Add a member
To add someone as a member to an org, you must add them to a
@@ -49,7 +61,7 @@ they will no longer have any access to the organization's repositories.
<%= headers 204 %>
-## List public members
+## Public members list
Members of an organization can choose to have their membership
publicized or not.
@@ -61,7 +73,7 @@ publicized or not.
<%= headers 200 %>
<%= json(:user) { |h| [h] } %>
-## Get if a user is a public member
+## Check public membership
GET /orgs/:org/public_members/:user
@@ -85,6 +97,6 @@ publicized or not.
DELETE /orgs/:org/public_members/:user
-## Response
+### Response
<%= headers 204 %>
diff --git a/content/v3/pulls.md b/content/v3/pulls.md
index 659e14d984..cbbcd126df 100644
--- a/content/v3/pulls.md
+++ b/content/v3/pulls.md
@@ -11,8 +11,8 @@ The Pull Request API allows you to list, view, edit, create, and even merge
pull requests. Comments on pull requests can be managed via the [Issue
Comments API](/v3/issues/comments/).
-Pull Requests leverage [these](#custom-mime-types) custom mime types. You
-can read more about the use of mime types in the API
+Pull Requests leverage [these custom media types](#custom-media-types). You
+can read more about the use of media types in the API
[here](/v3/media/).
## Link Relations
@@ -55,6 +55,8 @@ is `open`.
<%= headers 200 %>
<%= json :full_pull %>
+Pass the appropriate [media type](/v3/media/#commits-commit-comparison-and-pull-requests) to fetch diff and patch formats.
+
## Create a pull request
POST /repos/:owner/:repo/pulls
@@ -190,10 +192,10 @@ commit\_message
:message => 'Failure reason'
%>
-## Custom Mime Types
+## Custom media types
-These are the supported mime types for pull requests. You can read more about the
-use of mime types in the API [here](/v3/media/).
+These are the supported media types for pull requests. You can read more about the
+use of media types in the API [here](/v3/media/).
application/vnd.github.VERSION.raw+json
application/vnd.github.VERSION.text+json
diff --git a/content/v3/pulls/comments.md b/content/v3/pulls/comments.md
index f56a1606e6..eef44ff63d 100644
--- a/content/v3/pulls/comments.md
+++ b/content/v3/pulls/comments.md
@@ -12,8 +12,8 @@ diff. These are separate from Commit Comments (which are applied
directly to a commit, outside of the Pull Request view), and Issue
Comments (which do not reference a portion of the unified diff).
-Pull Request Review Comments leverage [these](#custom-mime-types) custom mime
-types. You can read more about the use of mime types in the API
+Pull Request Review Comments leverage [these custom media
+types](#custom-media-types). You can read more about the use of media types in the API
[here](/v3/media/).
## List comments on a pull request
@@ -25,6 +25,28 @@ types. You can read more about the use of mime types in the API
<%= headers 200 %>
<%= json(:pull_comment) { |h| [h] } %>
+## List comments in a repository
+
+ GET /repos/:owner/:repo/pulls/comments
+
+By default, Review Comments are ordered by ascending ID.
+
+### Parameters
+
+sort
+: _Optional_ **String** `created` or `updated`
+
+direction
+: _Optional_ **String** `asc` or `desc`. Ignored without `sort` parameter.
+
+since
+: _Optional_ **String** of a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+
+### Response
+
+<%= headers 200 %>
+<%= json(:pull_comment) { |h| [h] } %>
+
## Get a single comment
GET /repos/:owner/:repo/pulls/comments/:number
@@ -114,12 +136,13 @@ body
<%= headers 204 %>
-## Custom Mime Types
+## Custom media types
-These are the supported mime types for pull request comments. You can read
-more about the use of mime types in the API [here](/v3/media/).
+These are the supported media types for pull request comments. You can read
+more about the use of media types in the API [here](/v3/media/).
application/vnd.github.VERSION.raw+json
application/vnd.github.VERSION.text+json
application/vnd.github.VERSION.html+json
application/vnd.github.VERSION.full+json
+
diff --git a/content/v3/repos.md b/content/v3/repos.md
index ab1200e277..9269f0215e 100644
--- a/content/v3/repos.md
+++ b/content/v3/repos.md
@@ -50,13 +50,29 @@ List repositories for the specified org.
### Parameters
type
-: `all`, `public`, `member`, `private`. Default: `all`.
+: `all`, `public`, `private`, `forks`, `sources`, `member`. Default: `all`.
### Response
<%= headers 200, :pagination => true %>
<%= json(:repo) { |h| [h] } %>
+## List all repositories
+
+This provides a dump of every repository, in the order that they were created.
+
+ GET /repositories
+
+### Parameters
+
+since
+: The integer ID of the last Repository that you've seen.
+
+### Response
+
+<%= headers 200 %>
+<%= json(:repo) { |h| [h] } %>
+
## Create
Create a new repository for the authenticated user. OAuth users must supply
@@ -109,7 +125,8 @@ README. Default is `false`.
gitignore\_template
: _Optional_ **string** - Desired language or platform [.gitignore
template](https://github.com/github/gitignore) to
-apply. _Ignored if `auto_init` parameter is not provided._
+apply. Use the name of the template without the extension. For example, "Haskell"
+_Ignored if `auto_init` parameter is not provided._
<%= json \
:name => "Hello-World",
@@ -168,6 +185,9 @@ has\_downloads
: _Optional_ **boolean** - `true` to enable downloads for this
repository, `false` to disable them. Default is `true`.
+default\_branch
+: _Optional_ **String** - Update the default branch for this repository.
+
<%= json \
:name => "Hello-World",
:description => "This is your first repo",
diff --git a/content/v3/repos/comments.md b/content/v3/repos/comments.md
index 6d5ca7b14c..1bcc72e176 100644
--- a/content/v3/repos/comments.md
+++ b/content/v3/repos/comments.md
@@ -9,8 +9,8 @@ title: Repo Comments | GitHub API
## List commit comments for a repository
-Commit Comments leverage [these](#custom-mime-types) custom mime types. You can
-read more about the use of mime types in the API [here](/v3/media/).
+Commit Comments leverage [these custom media types](#custom-media-types). You can
+read more about the use of media types in the API [here](/v3/media/).
Comments are ordered by ascending ID.
@@ -101,10 +101,10 @@ body
<%= headers 204 %>
-## Custom Mime Types
+## Custom media types
-These are the supported mime types for commit comments. You can read more
-about the use of mime types in the API [here](/v3/media/).
+These are the supported media types for commit comments. You can read more
+about the use of media types in the API [here](/v3/media/).
application/vnd.github-commitcomment.raw+json
application/vnd.github-commitcomment.text+json
diff --git a/content/v3/repos/commits.md b/content/v3/repos/commits.md
index 05e1951013..bea243d67f 100644
--- a/content/v3/repos/commits.md
+++ b/content/v3/repos/commits.md
@@ -51,7 +51,9 @@ until
<%= headers 200 %>
<%= json(:full_commit) %>
-Note: Diffs with binary data will have no 'patch' property.
+Note: Diffs with binary data will have no 'patch' property. Pass the
+appropriate [media type](/v3/media/#commits-commit-comparison-and-pull-requests) to fetch diff and
+patch formats.
## Compare two commits
@@ -60,3 +62,5 @@ Note: Diffs with binary data will have no 'patch' property.
### Response
<%= json :commit_comparison %>
+
+Pass the appropriate [media type](/v3/media/#commits-commit-comparison-and-pull-requests) to fetch diff and patch formats.
diff --git a/content/v3/repos/contents.md b/content/v3/repos/contents.md
index e19c2cf902..2b8f0adbf1 100644
--- a/content/v3/repos/contents.md
+++ b/content/v3/repos/contents.md
@@ -8,7 +8,7 @@ title: Repo Contents | GitHub API
{:toc}
These API methods let you retrieve the contents of files within a repository as
-Base64 encoded content. See [Mime types](/v3/media/) for requesting raw or other formats.
+Base64 encoded content. See [media types](/v3/media/) for requesting raw or other formats.
## Get the README
diff --git a/content/v3/repos/downloads.md b/content/v3/repos/downloads.md
index 31a51c6263..62c1d47162 100644
--- a/content/v3/repos/downloads.md
+++ b/content/v3/repos/downloads.md
@@ -8,7 +8,7 @@ title: Repo Downloads | GitHub API
{:toc}
The downloads API is for package downloads only. If you want to get
-source tarballs you should use [this](/repos/contents/#get-archive-link)
+source tarballs you should use [this](/v3/repos/contents/#get-archive-link)
instead.
## List downloads for a repository
diff --git a/content/v3/repos/forks.md b/content/v3/repos/forks.md
index 9c423ac044..c1e8365538 100644
--- a/content/v3/repos/forks.md
+++ b/content/v3/repos/forks.md
@@ -27,9 +27,12 @@ Create a fork for the authenticated user.
POST /repos/:owner/:repo/forks
+One can either use the `organization` parameter or POST a JSON document with
+the field `organization`
+
### Parameters
-org
+organization
: _Optional_ **String** - Organization login. The repository will be
forked into this organization.
diff --git a/content/v3/repos/hooks.md b/content/v3/repos/hooks.md
index f7a151c0a2..4d6472f851 100644
--- a/content/v3/repos/hooks.md
+++ b/content/v3/repos/hooks.md
@@ -33,7 +33,7 @@ request is tracking).
* `status` - Any time a Repository has a status update from the API
The payloads for all of the hooks mirror [the payloads for the Event
-types](/v3/events/types/), with the exception of [the original `push`
+types](/v3/activity/events/types/), with the exception of [the original `push`
event](http://help.github.com/post-receive-hooks/).
For a Hook to go through, the Hook needs to be configured to trigger for
@@ -177,7 +177,9 @@ legacy format):
This will trigger the hook with the latest push to the current
repository.
- POST /repos/:owner/:repo/hooks/:id/test
+ POST /repos/:owner/:repo/hooks/:id/tests
+
+**Note**: Previously `/repos/:owner/:repo/hooks/:id/test`
### Response
diff --git a/content/v3/repos/statuses.md b/content/v3/repos/statuses.md
index 4ea226a292..6e4176b1da 100644
--- a/content/v3/repos/statuses.md
+++ b/content/v3/repos/statuses.md
@@ -11,14 +11,14 @@ The Status API allows external services to mark commits with a success,
failure, error, or pending `state`, which is then reflected in pull requests
involving those commits.
-Statuses can also include an optional `description` and `url`, and
+Statuses can also include an optional `description` and `target_url`, and
we highly recommend providing them as they make statuses much more
useful in the GitHub UI.
As an example, one common use is for continuous integration
services to mark commits as passing or failing builds using Status. The
`target_url` would be the full url to the build output, and the
-description would be the high level summary of what happened with the
+`description` would be the high level summary of what happened with the
build.
Note that the `repo:status` [OAuth scope](/v3/oauth/#scopes) grants targeted
@@ -63,8 +63,8 @@ description
<%= json \
:state => "success",
- :description => "The build succeeded!",
- :homepage => "https://example.com/build/status"
+ :target_url => "https://example.com/build/status",
+ :description => "The build succeeded!"
%>
### Response
diff --git a/content/v3/search.md b/content/v3/search.md
index 71c6171149..3ac0a9663b 100644
--- a/content/v3/search.md
+++ b/content/v3/search.md
@@ -60,6 +60,9 @@ Find users by keyword.
keyword
: Keyword search parameters
+start_page
+: _Optional_ Page number to fetch
+
<%= headers 200 %>
<%= json(:user_search_results) %>
diff --git a/content/v3/users.md b/content/v3/users.md
index 02217d634b..4bf5357301 100644
--- a/content/v3/users.md
+++ b/content/v3/users.md
@@ -73,3 +73,20 @@ bio
<%= headers 200 %>
<%= json :private_user %>
+## Get all users
+
+This provides a dump of every user, in the order that they signed up for
+GitHub.
+
+ GET /users
+
+### Parameters
+
+since
+: The integer ID of the last User that you've seen.
+
+### Response
+
+<%= headers 200 %>
+<%= json(:user) { |h| [h] } %>
+
diff --git a/content/v3/users/followers.md b/content/v3/users/followers.md
index bb29be9754..0c5a544df2 100644
--- a/content/v3/users/followers.md
+++ b/content/v3/users/followers.md
@@ -22,7 +22,7 @@ List the authenticated user's followers:
<%= headers 200, :pagination => true %>
<%= json(:user) { |h| [h] } %>
-## List users following another user
+## List users followed by another user
List who a user is following:
diff --git a/layouts/default.html b/layouts/default.html
index b200be7e15..003932c50f 100644
--- a/layouts/default.html
+++ b/layouts/default.html
@@ -42,13 +42,23 @@
diff --git a/lib/resources.rb b/lib/resources.rb
index cb75d77ec5..b11846a0fa 100644
--- a/lib/resources.rb
+++ b/lib/resources.rb
@@ -2,6 +2,7 @@
require 'yajl/json_gem'
require 'stringio'
require 'cgi'
+require 'securerandom'
module GitHub
module Resources
@@ -11,11 +12,15 @@ module Helpers
201 => '201 Created',
202 => '202 Accepted',
204 => '204 No Content',
+ 205 => '205 Reset Content',
301 => '301 Moved Permanently',
+ 302 => '302 Found',
+ 307 => '307 Temporary Redirect',
304 => '304 Not Modified',
401 => '401 Unauthorized',
403 => '403 Forbidden',
404 => '404 Not Found',
+ 405 => '405 Method not allowed',
409 => '409 Conflict',
422 => '422 Unprocessable Entity',
500 => '500 Server Error'
@@ -23,7 +28,9 @@ module Helpers
AUTHORS = {
:technoweenie => '821395fe70906c8290df7f18ac4ac6cf',
- :pengwynn => '7e19cd5486b5d6dc1ef90e671ba52ae0'
+ :pengwynn => '7e19cd5486b5d6dc1ef90e671ba52ae0',
+ :pezra => 'f38112009dc16547051c8ac246cee443',
+ :rick => 'a44d5abad6e86cff4e34d9f0839535c9'
}
DefaultTimeFormat = "%B %-d, %Y".freeze
@@ -87,6 +94,7 @@ def text_html(response, status, head = {})
res = CGI.escapeHTML(response)
hs + %() + res + "
"
end
+
end
USER = {
@@ -139,23 +147,26 @@ def text_html(response, status, head = {})
"key" => "ssh-rsa AAA...",
}
- REPO = {
+ SIMPLE_REPO = {
+ "id" => 1296269,
+ "owner" => USER,
+ "name" => "Hello-World",
+ "full_name" => "octocat/Hello-World",
+ "description" => "This your first repo!",
+ "private" => false,
+ "fork" => false,
"url" => "https://api.github.com/repos/octocat/Hello-World",
- "html_url" => "https://github.com/octocat/Hello-World",
+ "html_url" => "https://github.com/octocat/Hello-World"
+ }
+
+ REPO = SIMPLE_REPO.merge({
"clone_url" => "https://github.com/octocat/Hello-World.git",
"git_url" => "git://github.com/octocat/Hello-World.git",
"ssh_url" => "git@github.com:octocat/Hello-World.git",
"svn_url" => "https://svn.github.com/octocat/Hello-World",
"mirror_url" => "git://git.example.com/octocat/Hello-World",
- "id" => 1296269,
- "owner" => USER,
- "name" => "Hello-World",
- "full_name" => "octocat/Hello-World",
- "description" => "This your first repo!",
"homepage" => "https://github.com",
"language" => nil,
- "private" => false,
- "fork" => false,
"forks" => 9,
"forks_count" => 9,
"watchers" => 80,
@@ -166,7 +177,7 @@ def text_html(response, status, head = {})
"pushed_at" => "2011-01-26T19:06:43Z",
"created_at" => "2011-01-26T19:01:12Z",
"updated_at" => "2011-01-26T19:14:43Z"
- }
+ })
FULL_REPO = REPO.merge({
"organization" => USER.merge('type' => 'Organization'),
@@ -669,7 +680,7 @@ def text_html(response, status, head = {})
GIST_HISTORY = {
"history" => [
{
- "url" => "https://api.github.com/gists/1/57a7f021a713b1c5a6a199b54cc514735d2d462f",
+ "url" => "https://api.github.com/gists/#{SecureRandom.hex(10)}",
"version" => "57a7f021a713b1c5a6a199b54cc514735d2d462f",
"user" => USER,
"change_status" => {
@@ -682,11 +693,12 @@ def text_html(response, status, head = {})
]
}
+
GIST_FORKS = {
"forks" => [
{
"user" => USER,
- "url" => "https://api.github.com/gists/5",
+ "url" => "https://api.github.com/gists/#{SecureRandom.hex(10)}",
"created_at" => "2011-04-14T16:00:49Z"
}
]
@@ -699,13 +711,14 @@ def text_html(response, status, head = {})
}
GIST = {
- "url" => "https://api.github.com/gists/1",
+ "url" => "https://api.github.com/gists/#{SecureRandom.hex(10)}",
"id" => "1",
"description" => "description of gist",
"public" => true,
"user" => USER,
"files" => { "ring.erl" => GIST_FILE },
"comments" => 0,
+ "comments_url" => "https://api.github.com/gists/#{SecureRandom.hex(10)}/comments/",
"html_url" => "https://gist.github.com/1",
"git_pull_url" => "git://gist.github.com/1.git",
"git_push_url" => "git@gist.github.com:1.git",
@@ -717,7 +730,7 @@ def text_html(response, status, head = {})
GIST_COMMENT = {
"id" => 1,
- "url" => "https://api.github.com/gists/comments/1",
+ "url" => "https://api.github.com/gists/#{SecureRandom.hex(10)}/comments/1",
"body" => "Just commenting for the sake of commenting",
"user" => USER,
"created_at" => "2011-04-18T23:23:56Z"
@@ -957,6 +970,50 @@ def text_html(response, status, head = {})
:sha => "3a0f86fb8db8eea7ccbb9a95f325ddbedfb25e15",
:size => 100
}
+
+ THREAD = {
+ :id => 1,
+ :repository => SIMPLE_REPO,
+ :subject => {
+ :title => "Greetings",
+ :url => "https://api.github.com/repos/pengwynn/octokit/issues/123",
+ :latest_comment_url => "https://api.github.com/repos/pengwynn/octokit/issues/comments/123"
+ },
+ :reason => 'subscribed',
+ :unread => true,
+ :updated_at => '2012-09-25T07:54:41-07:00',
+ :last_read_at => '2012-09-25T07:54:41-07:00',
+ :url => "https://api.github.com/notifications/threads/1"
+ }
+
+ SUBSCRIPTION = {
+ :subscribed => true,
+ :ignored => false,
+ :reason => nil,
+ :created_at => "2012-10-06T21:34:12Z",
+ :url => "https://api.github.com/notifications/threads/1/subscription",
+ :thread_url => "https://api.github.com/notifications/threads/1"
+ }
+
+ REPO_SUBSCRIPTION = SUBSCRIPTION.merge \
+ :url => "https://api.github.com/repos/octocat/example/subscription",
+ :repository_url => "https://api.github.com/repos/octocat/example"
+ REPO_SUBSCRIPTION.delete :thread_url
+
+ TEMPLATE = {
+ :name => "C",
+ :source => "# Object files\n*.o\n\n# Libraries\n*.lib\n*.a\n\n# Shared objects (inc. Windows DLLs)\n*.dll\n*.so\n*.so.*\n*.dylib\n\n# Executables\n*.exe\n*.out\n*.app\n"
+ }
+
+ TEMPLATES = [
+ "Actionscript",
+ "Android",
+ "AppceleratorTitanium",
+ "Autotools",
+ "Bancha",
+ "C",
+ "C++"
+ ]
end
end
diff --git a/static/favicon.ico b/static/favicon.ico
index 47df9d03b0..712211126d 100644
Binary files a/static/favicon.ico and b/static/favicon.ico differ
diff --git a/static/images/posts/default-branch.png b/static/images/posts/default-branch.png
new file mode 100644
index 0000000000..335202ea38
Binary files /dev/null and b/static/images/posts/default-branch.png differ
diff --git a/static/shared/css/documentation.css b/static/shared/css/documentation.css
index f571401db0..1284e35db5 100644
--- a/static/shared/css/documentation.css
+++ b/static/shared/css/documentation.css
@@ -46,6 +46,8 @@ h2 {
body.api .change h2.title {
background: none;
+ line-height: 1.2em;
+ margin-bottom: 0;
padding-left: 0;
font-size:24px;
}