Organization Members Resource Changes
Requesting the member list of an organization of which you are not a member now redirects to the public members list. Similarly, requests to membership check resources of an organization of which you are not a member are redirected to the equivalent public membership check. One exception to the latter case is that if you are checking about your own membership the request is not redirected. You are always allowed to know what organizations you belong to.
The changes where made to clarify the purpose of these various resources. The
/orgs/:org/members
resources are intended for use by members of the
organization in question. The /orgs/:org/public_members
resources are for
acquiring information about the public membership of organizations. If you are
not a member you are not allowed to see private membership information so you
should be using the public membership resources.
If you have any questions or feedback, please drop us a line.
Rate limit changes for unauthenticated requests
To ensure a high quality of service for all API consumers, we've reduced the default rate limit for unauthenticated requests. To enjoy the default rate limit of 5,000 requests per hour, you'll need to authenticate via Basic Auth or OAuth. Unauthenticated requests will be limited to 60 per hour unless you include your OAuth client and secret.
We'll soon require all requests to include a valid User Agent header. Setting a unique value for this header helps us identify requests and get in touch with developers who are abusing the API. Most HTTP libraries, wrapper libraries, and even cURL provide a valid header for you already and allow you to change it to something unique to your application.
If you have any questions or feedback, please drop us a line.
Initialize a repository when creating
Today we've made it easier to add commits to a repository via the GitHub API. Until now, you could Create a repository for the authenticated user, but you would need to initialize it locally via your Git client before adding any commits via the API.
Now you can optionally init a repository when it's created by sending true
for the auto_init
parameter:
curl -i -u pengwynn \ -d '{"name": "create-repo-test", "auto_init": true}' \ https://api.github.com/user/repos
The resulting repository will have a README stub and an initial commit.
.gitignore templates
Along with this change, you can set up your .gitignore
template by passing
the basename of any template in the GitHub gitignore templates
project.
curl -i -u pengwynn \ -d '{"name": "create-repo-test", "auto_init": true, \ "gitignore_template": "Haskell"}' \ https://api.github.com/user/repos
The gitignore_template
parameter is ignored if auto_init
is not present and true
. For more information, see "Create a repository for the authenticated user."
If you have any questions or feedback, drop us a line at https://github.com/contact or @GitHubAPI.
Upcoming Changes to Watcher and Star APIs
We recently changed the Watcher behavior on GitHub. What used to be known as "Watching" is now "Starring". Starring is basically a way to bookmark interesting repositories. Watching is a way to indicate that you want to receive email or web notifications on a Repository.
This works well on GitHub.com, but poses a problem for the GitHub API. How do we change this in a way that developers can gracefully upgrade their applications? We're currently looking at rolling out the changes in three phases over an extended period of time.
Current Status
The current Repository Starring methods look like this:
-
/repos/:owner/:repo/watchers
- A list of users starring the repository. -
/users/:user/watched
- A list of repositories that a user has starred. -
/user/watched
- A list of repositories the current user has starred.
Phase 1: Add Watchers as Subscriptions
This phase exposes Watchers as "Subscriptions". This is to
keep from clashing with the legacy endpoints. This phase will happen
automatically and will not break your application until Phase 3 starts.
(UPDATE: API v3 will continue to support this functionality indefinitely.)
-
/repos/:owner/:repo/subscribers
- A list of users watching the repository. -
/users/:user/subscriptions
- A list of repositories that a user is watching. -
/user/subscriptions
- A list of repositories the current user is watching.
We'll also add a copy of the legacy Watchers API in the new endpoint:
-
/repos/:owner/:repo/stargazers
- A list of users starring the repository. -
/users/:user/starred
- A list of repositories that a user has starred. -
/user/starred
- A list of repositories the current user has starred.
This is in place now with the current media type for the API:
application/vnd.github.beta+json
If you care about your application not breaking, make sure all outgoing API
requests pass that value for the "Accept" header. You should do this now. This
can be verified by checking the X-GitHub-Media-Type
header on all API
responses.
# Accesses a user's starred repositories. curl https://api.github.com/user/watched \ -H "Accept: application/vnd.github.beta+json"
-This Phase will be broken once Phase 3 starts. Phase 3 removes all support for
the "beta" media type, and makes the "v3" media type the implicit default
for API requests.
UPDATE - November 6, 2013
API v3 will continue to officially support the functionality described in Phase 1 above. This functionality will remain intact for the lifetime of API v3.
API v3 will not include Phases 2 and 3 (below). Those phases will likely be part of the next major version of the API. (We have not announced a timeline for the next major version of the API.)
Phase 2: Switch /watchers
API Endpoint
/watchers
API EndpointThe "watch" endpoints will now be a copy of the "subscription" endpoints. You
will have to use /user/starred
to get a user's starred repositories, not
/user/watched
.
This requires a new media type value:
application/vnd.github.v3+json
This is a breaking change from Phase 1. We will release this change in an
experimental mode first, letting developers gracefully upgrade their
applications by specifying the new media value for the Accept header.
# Accesses a user's watched repositories. curl https://api.github.com/user/watched \ -H "Accept: application/vnd.github.v3+json"
Phase 3: Remove /subscribers
API Endpoint.
/subscribers
API Endpoint.This phase involves disabling the subscription endpoints completely. At this
point, you should be using the starring endpoints for starred repositories, and
the watch endpoints for watched repositories. No date has been set yet, but we
expect this to be 3-6 months after Phase 2 is in place. This should give
developers enough time for a smooth upgrade path. If they use popular API
wrappers, the work will likely mostly be done for them.
Keep on passing the "v3" media type in your application, until the API has
another breaking change to make. If you can't make the deadline for Phase 3,
just set the "beta" media type until we shut that down completely. It's likely
that we will keep the old "beta" media type active for another month, like
the last time we terminated
old API functionality.
We look forward to assisting you through this transition. Hit us up at https://github.com/contact or @GitHubAPI.