Initialize a repository when creating

2012-09-28T07:00:00Z

Today we’ve made it easier to add commits to a repository via the GitHub API. Until now, you could create a repository, 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

As the docs point out, the gitignore_template parameter is ignored if auto_init is not present and true.

If you have any questions or feedback, drop us a line at https://github.com/contact, [email protected]">[email protected], or @GitHubAPI.

Upcoming Changes to Watcher and Star APIs

2012-09-05T07:00:00Z

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.

/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.

Phase 2: Switch `/watchers` API Endpoint

The “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.

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, [email protected]">[email protected], or @GitHubAPI.

GitHub API Changes