Skip to content

Commit 8c8be73

Browse files
jasonrudolphjasonrudolph
committed
Document & announce the new Search API
- Move legacy search docs to a separate page (@gjtorikian) - Document new search API (@gjtorikian & @jasonrudolph) - Describe new /rate_limit response format (@jasonrudolph) - Move Rate Limit API to its own page - Describe the new (coming soon!) response format - Grab @gjtorikian's CSS from a recent PR [1] to highlight the fact that the Search API is in 'preview' mode (@jasonrudolph) - Sort "Overview" subsections in TOC (@jasonrudolph) - Fix hash linking TOC render (@gjtorikian) [1]: https://github.com/github/developer.github.com/pull/266/files#diff-1
1 parent d53c766 commit 8c8be73

File tree

9 files changed

+986
-85
lines changed

9 files changed

+986
-85
lines changed

‎content/changes/2013-07-19-preview-the-new-search-api.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
---
2+
kind: change
3+
title: Preview the New Search API
4+
created_at: 2013-07-19
5+
author_name: jasonrudolph
6+
---
7+
8+
Today we're excited to announce a [brand new Search API][docs]. Whether you're
9+
searching for [code][code-docs], [repositories][repo-docs],
10+
[issues][issue-docs], or [users][user-docs], all the query abilities of
11+
github.com are now available via the API as well.
12+
13+
Maybe you want to find [popular Tetris implementations written in Assembly][tetris-repos].
14+
We've got you covered.
15+
Or perhaps you're looking for [new gems that are using Octokit.rb][octokit-gemspecs].
16+
No problem.
17+
The possibilites are endless.
18+
19+
## Highlights
20+
21+
On github.com, we enjoy the context provided by code snippets and highlights in
22+
search results.
23+
24+
[![code-snippet-highlighting](https://f.cloud.github.com/assets/865/819651/959a4826-efb5-11e2-8af8-46c4a3857cdf.png)][example-web-search]
25+
26+
We want API consumers to have access to that information as well. So, API
27+
requests can opt to recieve those
28+
[text fragments in the response][text-matches]. Each fragment is accompanied by
29+
numeric offsets identifying the exact location of each matching search term.
30+
31+
## Preview period
32+
33+
We're making this new API available today for developers to
34+
[preview][preview-mode]. We think developers are going to love it, but we want
35+
to get your feedback before we declare the Search API "final" and
36+
"unchangeable." We expect the preview period to last for roughly 60 days.
37+
38+
As we discover opportunities to improve this new API during the preview period,
39+
we may ship changes that break clients using the preview version of the API. We
40+
want to iterate quickly. To do so, we will announce any changes here (on the
41+
developer blog), but we will not provide any advance notice.
42+
43+
At the end of preview period, the Search API will become an official component
44+
of GitHub API v3. At that point, the new Search API will be stable and suitable
45+
for production use.
46+
47+
## What about the old search API?
48+
49+
The [legacy search API][legacy-search] is still available. Many existing clients
50+
depend on it, and it is not changing in any way. While the new API offers much
51+
more functionality, the legacy search endpoints remain an official part of
52+
GitHub API v3.
53+
54+
## Take it for a spin
55+
56+
We hope you'll kick the tires and [send us your feedback][contact]. Happy
57+
<del>searching</del> finding!
58+
59+
[code-docs]: /v3/search/#search-code
60+
[contact]: https://github.com/contact?form[subject]=New+Search+API
61+
[docs]: /v3/search/
62+
[example-web-search]: https://github.com/search?q=faraday+builder+repo%3Aoctokit%2Foctokit.rb&type=Code
63+
[issue-docs]: /v3/search/#search-issues
64+
[legacy-search]: /v3/search/legacy/
65+
[octokit-gemspecs]: /v3/search/#code-search-example
66+
[preview-mode]: /v3/search/#preview-mode
67+
[repo-docs]: /v3/search/#search-repositories
68+
[tetris-repos]: /v3/search/#repository-search-example
69+
[text-matches]: /v3/search#text-match-metadata
70+
[user-docs]: /v3/search/#search-users

‎content/v3.md‎

Lines changed: 9 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -250,7 +250,7 @@ see [events](http://developer.github.com/v3/activity/events/) for example.
250250
$ curl https://api.github.com/user/repos?page=2&per_page=100
251251
</pre>
252252

253-
Note that page numbering is 1-based and that ommiting the `?page`
253+
Note that page numbering is 1-based and that ommiting the `?page`
254254
parameter will return the first page.
255255

256256
### Link Header
@@ -283,12 +283,13 @@ The possible `rel` values are:
283283

284284
## Rate Limiting
285285

286-
We limit requests to 60 per hour for unauthenticated requests. For requests
287-
using Basic Authentication or OAuth, we limit requests to 5,000
288-
per hour.
286+
For requests using Basic Authentication or OAuth, you can make up to 5,000
287+
requests per hour. For unauthenticated requests, the rate limit allows you to
288+
make up to 60 requests per hour. (The Search API has [custom rate limit
289+
rules](/v3/search/#rate-limit).)
289290

290291
You can check the returned HTTP headers of any API request to see your current
291-
status:
292+
rate limit status:
292293

293294
<pre class="terminal">
294295
$ curl -i https://api.github.com/users/whatever
@@ -319,20 +320,8 @@ new Date(1372700873 * 1000)
319320
// => Mon Jul 01 2013 13:47:53 GMT-0400 (EDT)
320321
</code></pre>
321322

322-
You can also check your rate limit status without incurring an API hit.
323-
324-
GET /rate_limit
325-
326-
### Rate limit
327-
328-
<%=
329-
headers 200,
330-
'X-RateLimit-Limit' => 5000,
331-
'X-RateLimit-Remaining' => 4999,
332-
'X-RateLimit-Reset' => 1372700873
333-
%>
334-
<%= json :rate => {:limit => 5000, :remaining => 4999, :reset => 1372700873} %>
335-
323+
You can also [check your rate limit status](/v3/rate_limit) without incurring an
324+
API hit.
336325
<br>
337326

338327
### Unauthenticated rate limited requests
@@ -368,7 +357,7 @@ higher rate limit for your OAuth application.
368357
## User Agent Required
369358

370359
All API requests MUST include a valid `User-Agent` header. Requests with no `User-Agent`
371-
header will be rejected. We request that you use your GitHub username, or the name of your
360+
header will be rejected. We request that you use your GitHub username, or the name of your
372361
application, for the `User-Agent` header value. This allows us to contact you if there are problems.
373362

374363
Here's an example:

‎content/v3/rate_limit.md‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: GitHub Rate Limit API | GitHub API
3+
---
4+
5+
# GitHub Rate Limit API
6+
7+
The overview documentation describes the [rate limit rules](/v3/#rate-limiting).
8+
You can check your current rate limit status at any time using the Rate Limit
9+
API described below.
10+
11+
## Get your current rate limit status
12+
13+
Note: Accessing this endpoint does not count against your rate limit.
14+
15+
GET /rate_limit
16+
17+
### Response
18+
19+
<%=
20+
headers 200,
21+
'X-RateLimit-Limit' => 5000,
22+
'X-RateLimit-Remaining' => 4999,
23+
'X-RateLimit-Reset' => 1372700873
24+
%>
25+
<%= json :rate => {:limit => 5000, :remaining => 4999, :reset => 1372700873} %>
26+
<br>
27+
28+
#### Future response
29+
30+
The current response (shown above) provides the rate limit status for _most_ of
31+
the API. However, the Search API has a [custom rate limit](/v3/search/#rate-
32+
limit), separate from the rate limit governing the rest of the API. For that
33+
reason, this endpoint will
34+
[soon](/changes/2013-07-19-preview-the-new-search-api) begin returning a
35+
`"resources"` hash, which provides the rate limit status for all API resources.
36+
37+
To get this response format today, use the `application/vnd.github.preview`
38+
[media type](/v3/media).
39+
40+
<%=
41+
headers 200,
42+
'X-RateLimit-Limit' => 5000,
43+
'X-RateLimit-Remaining' => 4999,
44+
'X-RateLimit-Reset' => 1372700873
45+
%>
46+
<%=
47+
json :rate => {:limit => 5000, :remaining => 4999, :reset => 1372700873},
48+
:resources => {
49+
:core => {:limit => 5000, :remaining => 4999, :reset => 1372700873},
50+
:search => {:limit => 20, :remaining => 18, :reset => 1372697452},
51+
}
52+
%>

0 commit comments

Comments
 (0)