|
| 1 | +--- |
| 2 | +title: Versions | GitHub API |
| 3 | +--- |
| 4 | +# Versions |
| 5 | + |
| 6 | +There are two stable versions of the GitHub API: [beta](#beta) and [v3](#v3). There are just a few [differences between these two versions](#/v3/media/#beta-v3-and-the-future). |
| 7 | + |
| 8 | +By default, all requests receive the beta version. We encourage you to [request a specific version via the `Accept` header](#/v3/media/#beta-v3-and-the-future). |
| 9 | + |
| 10 | +# v3 |
| 11 | + |
| 12 | +The [v3 API](/v3) is stable and unchangeable. Please [file a support issue][support] if you have problems. |
| 13 | + |
| 14 | +Some v3 functionality is [deprecated](#v3-deprecations) and will be removed in the next major version of the API. |
| 15 | + |
| 16 | +## Differences from beta version |
| 17 | + |
| 18 | +The v3 media type differs from the beta media type in just a few places: |
| 19 | + |
| 20 | +### Gist JSON |
| 21 | + |
| 22 | +For [Gists](/v3/gists/#get-a-single-gist), the v3 media type renames the `user` attribute to `owner`. |
| 23 | + |
| 24 | +### Issue JSON |
| 25 | + |
| 26 | +When an [issue](/v3/issues/#get-a-single-issue) is not a pull request, the v3 media type omits the `pull_request` attribute. |
| 27 | + |
| 28 | +### Repository JSON |
| 29 | + |
| 30 | +For [Repositories](/v3/repos/#get), the v3 media type omits the `master_branch` attribute. API clients should use the `default_branch` attribute to obtain the repository's default branch. |
| 31 | + |
| 32 | +### User JSON |
| 33 | + |
| 34 | +For [Users](/v3/users/), the v3 media type omits the `public_gists` and `private_gists` attributes. |
| 35 | + |
| 36 | +### User Emails JSON |
| 37 | + |
| 38 | +For [User Emails](/v3/users/emails/#list-email-addresses-for-a-user), the v3 media type returns an array of hashes (instead of an array of strings). |
| 39 | + |
| 40 | +## v3 deprecations |
| 41 | + |
| 42 | +The following functionality is deprecated. For backwards compatibility purposes, |
| 43 | +v3 will continue to provide this functionality. However, this deprecated |
| 44 | +functionality _will be removed_ in the next major version of the API. |
| 45 | + |
| 46 | +The recommendations below will help you prepare your application for the next major version of the API. |
| 47 | + |
| 48 | +1. Method: /gists/:id/fork |
| 49 | +: Recommendation: Use **/gists/:id/forks** (plural) instead. |
| 50 | + |
| 51 | +1. Method: /legacy/issues/search/:owner/:repository/:state/:keyword |
| 52 | +: Recommendation: Use [v3 Issue Search API](/v3/search/#search-issues) instead. |
| 53 | + |
| 54 | +1. Method: /legacy/repos/search/:keyword |
| 55 | +: Recommendation: Use [v3 Repository Search API](/v3/search/#search-repositories) instead. |
| 56 | + |
| 57 | +1. Method: /legacy/user/search/:keyword |
| 58 | +: Recommendation: Use [v3 User Search API](/v3/search/#search-users) instead. |
| 59 | + |
| 60 | +1. Method: /legacy/user/email/:email |
| 61 | +: Recommendation: Use [v3 User Search API](/v3/search/#search-users) instead. |
| 62 | + |
| 63 | +1. Method: /repos/:owner/:repo/hooks/:id/test |
| 64 | +: Recommendation: Use **/repos/:owner/:repo/hooks/:id/tests** (plural) instead. |
| 65 | + |
| 66 | +1. Query parameters when POSTing to /repos/:owner/:repo/forks |
| 67 | +: Recommendation: Use JSON to POST to this method instead. |
| 68 | + |
| 69 | +1. Query parameter value: Passing "watchers" as the value for the "sort" parameter in a GET request to /repos/:owner/:repo/forks |
| 70 | +: Recommendation: Use **stargazers** as the value instead. |
| 71 | + |
| 72 | +1. Pull Request attribute: merge_commit_sha |
| 73 | +: Recommendation: [Do not use this attribute](/changes/2013-04-25-deprecating-merge-commit-sha/). |
| 74 | + |
| 75 | +1. Rate Limit attribute: rate |
| 76 | +: Recommendation: Use **resources["core"]** instead. |
| 77 | + |
| 78 | +1. Repository attribute: forks |
| 79 | +: Recommendation: Use **fork_count** instead. |
| 80 | + |
| 81 | +1. Repository attribute: master_branch |
| 82 | +: Recommendation: Use **default_branch** instead. |
| 83 | + |
| 84 | +1. Repository attribute: open_issues |
| 85 | +: Recommendation: Use **open_issues_count** instead. |
| 86 | + |
| 87 | +1. Repository attribute: public |
| 88 | +: Recommendation: When [creating a repository](/v3/repos/#create), use the |
| 89 | + **private** attribute to indicate whether the repository should be public or |
| 90 | + private. Do not use the **public** attribute. |
| 91 | + |
| 92 | +1. Repository attribute: watchers |
| 93 | +: Recommendation: Use **watchers_count** instead. |
| 94 | + |
| 95 | +1. User attribute: bio |
| 96 | +: Recommendation: Do not use this attribute. It is obsolete. |
| 97 | + |
| 98 | + |
| 99 | +# beta |
| 100 | + |
| 101 | +The [beta API](/v3) is now stable and unchangeable. Please [file a support issue][support] if you have problems. |
| 102 | + |
| 103 | +## Breaking beta changes |
| 104 | + |
| 105 | +### June 15th, 2011: |
| 106 | + |
| 107 | +* `gravatar_url` is being deprecated in favor of `avatar_url` for all |
| 108 | + responses that include users or orgs. A default size is no longer |
| 109 | + included in the URL. |
| 110 | +* Creating new gists (both anonymously and with an authenticated user) |
| 111 | + should use `POST /gists` from now on. `POST /users/:user/gists` is no |
| 112 | + longer supported. |
| 113 | + |
| 114 | +### June 1st, 2011: |
| 115 | + |
| 116 | +* Removed support for PUT verb on update requests. Use POST or PATCH |
| 117 | + instead. |
| 118 | +* Removed `.json` extension from all URLs. |
| 119 | +* No longer using the X-Next or X-Last headers. Pagination info is |
| 120 | + returned in the Link header instead. |
| 121 | +* JSON-P response has completely changed to a more consistent format. |
| 122 | +* Starring gists now uses PUT verb (instead of POST) and returns 204. |
| 123 | + |
| 124 | +# v2 |
| 125 | + |
| 126 | +We removed support for API v2 on June 12, 2012. |
| 127 | + |
| 128 | +# v1 |
| 129 | + |
| 130 | +We removed support for API v1 on June 12, 2012. |
| 131 | + |
| 132 | +[support]: https://github.com/contact?form[subject]=APIv3 |
0 commit comments