Skip to content

versions.md

Latest commit

 

History

History
130 lines (82 loc) · 5.14 KB

versions.md

File metadata and controls

130 lines (82 loc) · 5.14 KB
title Versions | GitHub API

Versions

There are two stable versions of the GitHub API: beta and v3. There are just a few differences between these two versions.

By default, all requests receive the beta version. Soon, v3 will become the default version. (Check out the blog post for details.) We encourage you to request a specific version via the Accept header.

v3

The v3 API is stable and unchangeable. Please file a support issue if you have problems.

Some v3 functionality is deprecated and will be removed in the next major version of the API.

Differences from beta version

The v3 media type differs from the beta media type in just a few places:

Gist JSON

For Gists, the v3 media type renames the user attribute to owner.

Issue JSON

When an issue is not a pull request, the v3 media type omits the pull_request attribute.

Repository JSON

For Repositories, the v3 media type omits the master_branch attribute. API clients should use the default_branch attribute to obtain the repository's default branch.

User Emails JSON

For User Emails, the v3 media type returns an array of hashes (instead of an array of strings).

v3 deprecations

The following functionality is deprecated. For backwards compatibility purposes, v3 will continue to provide this functionality. However, this deprecated functionality will be removed in the next major version of the API.

The recommendations below will help you prepare your application for the next major version of the API.

  1. Method: /gists/:id/fork : Recommendation: Use /gists/:id/forks (plural) instead.

  2. Method: /legacy/issues/search/:owner/:repository/:state/:keyword : Recommendation: Use v3 Issue Search API instead.

  3. Method: /legacy/repos/search/:keyword : Recommendation: Use v3 Repository Search API instead.

  4. Method: /legacy/user/search/:keyword : Recommendation: Use v3 User Search API instead.

  5. Method: /legacy/user/email/:email : Recommendation: Use v3 User Search API instead.

  6. Method: /repos/:owner/:repo/hooks/:id/test : Recommendation: Use /repos/:owner/:repo/hooks/:id/tests (plural) instead.

  7. Query parameters when POSTing to /repos/:owner/:repo/forks : Recommendation: Use JSON to POST to this method instead.

  8. Query parameter value: Passing "watchers" as the value for the "sort" parameter in a GET request to /repos/:owner/:repo/forks : Recommendation: Use stargazers as the value instead.

  9. Pull Request attribute: merge_commit_sha : Recommendation: Do not use this attribute.

  10. Rate Limit attribute: rate : Recommendation: Use resources["core"] instead.

  11. Repository attribute: forks : Recommendation: Use fork_count instead.

  12. Repository attribute: master_branch : Recommendation: Use default_branch instead.

  13. Repository attribute: open_issues : Recommendation: Use open_issues_count instead.

  14. Repository attribute: public : Recommendation: When creating a repository, use the private attribute to indicate whether the repository should be public or private. Do not use the public attribute.

  15. Repository attribute: watchers : Recommendation: Use watchers_count instead.

  16. User attribute: bio : Recommendation: Do not use this attribute. It is obsolete.

beta

The beta API is now stable and unchangeable. Please file a support issue if you have problems.

Starting April 15, 2014, the beta version will no longer be the default version. However, we expect to continue supporting the beta version for a while. We will eventually retire the beta version, but we have no official retirement date to annouce at the moment. When the time comes, rest assured that we'll announce the retirement with plenty of notice.

Breaking beta changes

June 15th, 2011:

  • gravatar_url is being deprecated in favor of avatar_url for all responses that include users or orgs. A default size is no longer included in the URL.
  • Creating new gists (both anonymously and with an authenticated user) should use POST /gists from now on. POST /users/:user/gists is no longer supported.

June 1st, 2011:

  • Removed support for PUT verb on update requests. Use POST or PATCH instead.
  • Removed .json extension from all URLs.
  • No longer using the X-Next or X-Last headers. Pagination info is returned in the Link header instead.
  • JSON-P response has completely changed to a more consistent format.
  • Starring gists now uses PUT verb (instead of POST) and returns 204.

v2

We removed support for API v2 on June 12, 2012.

v1

We removed support for API v1 on June 12, 2012.