<p>On April 15, 2014<ahref="#cutover-test">*</a>, the GitHub API will start serving the v3 media type by default. The information below will help you determine whether your applications will be affected by this change. For affected applications, you’ll find tips below to help you smoothly navigate this change.</p>
<h2id="whats-changing">What’s changing?</h2>
<h3id="a-new-default-version">A new default version</h3>
<p>There are <ahref="/v3/versions">two versions</a> of the GitHub API: <strong>beta</strong> and <strong>v3</strong>. Today, requests receive the beta version by default. On April 15<ahref="#cutover-test">*</a>, requests will begin receiving the v3 version by default.</p>
<p>For the most part, beta and v3 are remarkably similar. There are <ahref="/v3/versions/#differences-from-beta-version">just a few differences</a> to keep in mind.</p>
<h3id="a-new-default-media-type">A new default media type</h3>
<p>The version is one part of the <ahref="/v3/media">media type</a>. By default, the API provides the beta media type:</p>
<pre><code>application/vnd.github.beta+json
</code></pre>
<p>On April 15<ahref="#cutover-test">*</a>, requests will begin responding with the v3 media type by default:</p>
<pre><code>application/vnd.github.v3+json
</code></pre>
<h2id="who-is-affected">Who is affected?</h2>
<p>Since 2012, we have encouraged developers to explicitly <ahref="/v3/media/#beta-v3-and-the-future">request a specific media type via the <code>Accept</code> header</a>. If you are requesting either beta or v3 via the <code>Accept</code> header, then you are <em>not</em> affected by this change. The API will continue to respond with the requested media type.</p>
<p>If you are not requesting beta or v3 via the <code>Accept</code> header, then the API is currently responding with the beta media type. On April 15<ahref="#cutover-test">*</a>, the API will begin responding with the v3 media type. If your application relies on <ahref="/v3/versions/#differences-from-beta-version">functionality that differs between beta and v3</a>, then you are affected by this change. You will need to take steps to prepare for the change.</p>
<h2id="what-should-you-do">What should you do?</h2>
<p>If you are affected by this change, we recommend that you:</p>
<ol>
<li>Update your applications to depend on the v3 functionality instead of the beta functionality. (If you use one of the popular <ahref="/libraries/">client libraries</a>, there’s a good chance that they’ve already done the work for you. In that case, you can just update to the latest version of that library.)</li>
<li>Request the v3 media type via the <code>Accept</code> header.</li>
</ol>
<p>If you cannot update your application to depend on the v3 functionality by April 15<ahref="#cutover-test">*</a>, you can just request the beta media type via the <code>Accept</code> header. Doing so will insulate you from this change.</p>
<h2id="cutover-test">Cutover test on March 12, 2014</h2>
<p>To help you understand the impact of this change before it becomes permanent, we will temporarily implement this change for a single day on March 12. From approximately 12:01am UTC to 11:59pm UTC on March 12, the API will respond with the v3 media type by default.</p>
<p>Follow <ahref="https://twitter.com/GitHubAPI">@GitHubAPI</a> to receive updates before and after the test.</p>
<h2id="stay-informed">Stay informed</h2>
<p>Depending on the results of the cutover test, we may schedule additional tests before the final cutover on April 15. If so, we’ll to announce them in advance. Be sure to stay tuned to the <ahref="/changes">blog</a> or follow <ahref="https://twitter.com/GitHubAPI">@GitHubAPI</a> for updates.</p>
<p>If you have any questions, please <ahref="https://github.com/contact?form%5Bsubject%5D=Upcoming+change+to+default+API+media+type">get in touch</a>. We’ll be happy to help.</p>
<p>The <ahref="http://developer.github.com/v3/orgs/members/#members-list">organization members</a> and <ahref="http://developer.github.com/v3/orgs/members/#public-members-list">organization public members</a> methods will soon return paginated results by default. Beginning
today, these methods will paginate if you include <code>page</code> or <code>per_page</code> query
parameters. Starting January 15th, 2014, these methods will <em>always</em> return paginated
results.</p>
<p>As always, be sure and follow those <ahref="http://developer.github.com/v3/#pagination">Link headers</a> to get
subsequent results. If you have any questions or run into trouble, feel free to
<ahref="https://github.com/contact?form%5Bsubject%5D=API+v3:+Paginating+org+members">get in touch</a>.</p>
<p>Hot on the heels of the <ahref="http://developer.github.com/changes/2013-10-29-search-api-becomes-an-official-part-of-github-api-v3/">Search API</a>, the <ahref="/v3/repos/releases/">Releases API</a>
is now officially part of GitHub API v3. We now consider it stable for
production use. </p>
<h3id="preview-media-type-no-longer-needed">Preview Media Type No Longer Needed</h3>
<p>If you used the Releases API during the preview period, you needed to provide a custom media type in the <code>Accept</code> header:</p>
<p>We’re excited to announce that the <ahref="/v3/search">new Search API</a> has graduated from <ahref="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview mode</a>.
As of today, the Search API is an official part of <ahref="/v3">GitHub API v3</a>.
As such, the Search API is now stable and suitable for production use.</p>
<h3id="preview-media-type-no-longer-needed">Preview Media Type No Longer Needed</h3>
<p>If you used the Search API during the preview period, you needed to provide a custom media type in the <code>Accept</code> header:</p>
<pre><code>application/vnd.github.preview+json
</code></pre>
<p>Now that the preview period has ended, you no longer need to pass this custom media type.</p>
<p>Instead, we <ahref="/v3/media">recommend</a> that you specify <code>v3</code> as the version in the <code>Accept</code> header:</p>
<pre><code>application/vnd.github.v3+json
</code></pre>
<h3id="onward">Onward!</h3>
<p>Thanks again to everyone that tried out the Search API during the preview period.</p>
<p>In order to support the expected volume of requests, we’re applying a new validation rule to the <ahref="/v3/search/#search-code">Code Search API</a>.
Starting today, you will need to scope your code queries to a specific set of users, organizations, or repositories.</p>
<p>As usual, you specify the query via the <code>q</code> parameter.
The value must include <ahref="https://help.github.com/articles/searching-code#users-organizations-and-repositories">at least one user, organization, or repository</a>.</p>
<p>For example, with this query, we’re searching for code from <ahref="https://github.com/twitter">@twitter</a> or <ahref="https://github.com/facebook">@facebook</a> that uses an MIT License:</p>
<pre><code>MIT License user:twitter user:facebook
</code></pre>
<p>And here, we’re looking for uses of the underscore library in <ahref="https://github.com/mozilla/BrowserQuest">@mozilla’s BrowserQuest</a> repository:</p>
<p>All the various <ahref="https://help.github.com/articles/searching-code">code search qualifiers</a> are still available to you.
A <ahref="https://help.github.com/articles/searching-code#users-organizations-and-repositories">user, organization, or repository qualifier</a> is now required.
The other search qualifiers are still optional.</p>
<h2id="other-search-types-not-affected">Other Search Types Not Affected</h2>
<p>This new validation only applies to the <ahref="/v3/search/#search-code">Code Search API</a>.
It does not apply to the Search API for <ahref="/v3/search/#search-issues">issues</a>, <ahref="/v3/search/#search-users">users</a>, or <ahref="/v3/search/#search-repositories">repositories</a>.</p>
<p>This validation does not affect searches performed on <ahref="https://github.com/search">github.com/search</a>.</p>
<p>By ensuring that code queries are more targeted in nature, the API will be ready to meet the expected demand from all your apps.
As we continue to tune the Search API, we hope to relax this validation in the future.
There’s no ETA, but we’d like to relax it as soon as it’s feasible.</p>
<p>As always, if you have any questions or feedback, please <ahref="https://github.com/contact?form%5Bsubject%5D=New+Validation+Rule+for+Code+Search+API">get in touch</a>.</p>
<p>As always, if you have any questions or feedback, please <ahref="https://github.com/contact?form%5Bsubject%5D=API+-+Listing+Teams+for+User">drop us a line</a>.</p>
<p>We owe a big “Thank You!” to everyone that has taken the time to try out the <ahref="/changes/2013-07-19-preview-the-new-search-api">new Search API</a>.
We <code>:heart:</code> every one of you.
Just as we hoped,
the <ahref="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview period</a> has allowed us to see how you want to use the new API,
and it has given us a chance to improve the API before finalizing it.</p>
<p>In order to incorporate everything that we’ve learned,
we’re going to keep the Search API in <ahref="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview mode</a> for a little while longer.
We have a few bugs to squash and a couple performance kinks to iron out.
We’re hard at work on those improvements now,
and we expect to have more news in the coming weeks.</p>
<p>In the mean time, <ahref="https://github.com/contact?form%5Bsubject%5D=New+Search+API">keep the suggestions coming</a>!</p>
<p>This summer we made it easier to <ahref="https://github.com/blog/1547-release-your-software">release your software</a>. Today, you can fully automate those releases via the
<ahref="http://developer.github.com/v3/repos/releases/">Releases API Preview</a>.</p>
<p>This API is a little different due to the binary assets. We use the <code>Accept</code> header for content negotiation when requesting
a release asset. Pass a standard API media type to get the API representation:</p>
<p>The new API is available as a <ahref="http://developer.github.com/v3/repos/releases/#preview-mode">preview</a>. This gives developers a chance to <ahref="https://github.com/contact?form%5Bsubject%5D=New+Releases+API">provide feedback</a> on the direction of
the API before we freeze changes. We expect to lift the preview status in 30 days.</p>
<p>As with <ahref="http://developer.github.com/changes/2013-07-19-preview-the-new-search-api/">the Search API</a>, we’ll take this opportunity to iterate quickly. Breaking changes will be announced
on this developer blog without any advance warning. Once the preview period is over, we’ll consider the Releases API unchangeable.
At that point, it will be stable and suitable for production use.</p>
<p>The preview media type is “application/vnd.github.manifold-preview”. <ahref="http://en.wikipedia.org/wiki/Eden_Fesi">Manifold</a> is
a member of the Avengers, with the ability to teleport through time and space. He’s the one in the middle holding the spear.</p>
<p><imgsrc="https://f.cloud.github.com/assets/21/1210628/ae8556fa-25fc-11e3-986d-0ab522271d43.png" alt="Manifold teleporting the Avengers to a terraformed Mars surface"></p>
<p>Personal access tokens provide the simplest option for using 2FA with Basic
Authentication. You can create these tokens via the <ahref="https://github.com/settings/applications">application settings page
on GitHub.com</a>, and you can revoke
them at any time. For more information about authenticating to the API with
personal access tokens, be sure to check out our <ahref="https://help.github.com/articles/creating-an-access-token-for-command-line-use">help article on the
<p>Today we’re shipping two improvements to the <ahref="/changes/2013-07-19-preview-the-new-search-api/">new Search API</a>.</p>
<h2id="more-text-match-metadata">More Text Match Metadata</h2>
<p>When searching for code, the API previously provided <ahref="/v3/search/#text-match-metadata">text match metadata</a> (i.e., “highlights”) for file content.
Now, you can also <ahref="/v3/search/#highlighting-code-search-results">get this metadata</a> for matches that occur within the file path.</p>
<p>For example, when <ahref="https://github.com/search?q=%40octokit%2Foctokit.rb+in%3Apath+client&type=Code">searching for files that have “client” in their path</a>, the results include this match for <code>lib/octokit/client/commits.rb</code>:</p>
<p>The response would include a <code>text_matches</code> array with the following object:</p>
<preclass="json">
{
"fragment": "undefined method `except' for #&lt;Array:XXX&gt;",
// ...
}
</pre>
<p>Inside the <code>fragment</code> value, we see HTML-encoded entities (e.g., <code>&lt;</code>).
Since we’re returning JSON (not HTML), API clients might not expect any HTML-encoded text.
As of today, the API returns these fragments <em>without</em> this extraneous encoding.</p>
<preclass="json">
{
"fragment": "undefined method `except' for #<Array:XXX>",
// ...
}
</pre>
<h2id="preview-period">Preview Period</h2>
<p>We’re about halfway through the <ahref="/changes/2013-07-19-preview-the-new-search-api/#preview-period">preview period</a> for the new Search API.
We appreciate everyone that has provided feedback so far. Please <ahref="https://github.com/contact?form%5Bsubject%5D=New+Search+API">keep it coming</a>!</p>
<p>Have you ever wondered when your <ahref="/v3/#rate-limiting">rate limit</a> will reset back to its maximum value?
That information is now available in the new <code>X-RateLimit-Reset</code> response header.</p>
<preclass="terminal">
$ curl -I https://api.github.com/orgs/octokit
HTTP/1.1 200 OK
Status: 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1372700873
...
</pre>
<p>The <code>X-RateLimit-Reset</code> header provides a <ahref="http://en.wikipedia.org/wiki/Unix_time">Unix UTC timestamp</a>, letting you know the exact time that your fresh new rate limit kicks in.</p>
<p>The reset timestamp is also available as part of the <code>/rate_limit</code> resource.</p>
<preclass="terminal">
$ curl https://api.github.com/rate_limit
{
"rate": {
"limit": 60,
"remaining": 42,
"reset": 1372700873
}
}
</pre>
<p>For more information on rate limits, be sure to check out the <ahref="/v3/#rate-limiting">docs</a>.</p>
<p>If you have any questions or feedback, please <ahref="https://github.com/contact?form%5Bsubject%5D=X-RateLimit-Reset">drop us a line</a>.</p>