[refs #374] Patch Rack::Throttle http_error method. Finish main page
text
This commit is contained in:
konstantin.grabar
parent
11b7834bbc
commit
f7d28dd23c
|
|
@ -16,18 +16,14 @@ All of the urls in this manual have the same tail: .json. Because the default
|
|||
* <a href="#authentication">Authentication</a>
|
||||
* <a href="#pagination">Pagination</a>
|
||||
* <a href="#rate-limiting">Rate Limiting</a>
|
||||
* <a href="#conditional-requests">Conditional Requests</a>
|
||||
* <a href="#cross-origin-resource-sharing">Cross Origin Resource Sharing</a>
|
||||
* <a href="#json-p-callbacks">JSON-P Callbacks</a>
|
||||
|
||||
## Schema
|
||||
|
||||
All API access is over HTTPS, and accessed from the `api.github.com`
|
||||
domain (or through `yourdomain.com/api/v3/` for enterprise). All data is
|
||||
All API access is over HTTPS and all data is
|
||||
sent and received as JSON.
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl -i https://api.github.com
|
||||
$ curl -i https://abf.rosalinux.ru
|
||||
|
||||
HTTP/1.1 302 Found
|
||||
Server: nginx/1.0.12
|
||||
|
|
@ -35,88 +31,54 @@ Date: Mon, 20 Feb 2012 11:15:49 GMT
|
|||
Content-Type: text/html;charset=utf-8
|
||||
Connection: keep-alive
|
||||
Status: 302 Found
|
||||
X-RateLimit-Limit: 5000
|
||||
ETag: "d41d8cd98f00b204e9800998ecf8427e"
|
||||
Location: http://developer.github.com
|
||||
X-RateLimit-Remaining: 4999
|
||||
X-RateLimit-Limit: 500
|
||||
Location: http://abf.rosalinux.ru
|
||||
X-RateLimit-Remaining: 499
|
||||
Content-Length: 0
|
||||
|
||||
</pre>
|
||||
|
||||
Blank fields are included as `null` instead of being omitted.
|
||||
|
||||
All timestamps are returned in ISO 8601 format:
|
||||
All timestamps are returned in unixtime format:
|
||||
|
||||
YYYY-MM-DDTHH:MM:SSZ
|
||||
1346762587
|
||||
|
||||
## Client Errors
|
||||
|
||||
There are three possible types of client errors on API calls that
|
||||
receive request bodies:
|
||||
|
||||
1. Sending invalid JSON will result in a `400 Bad Request` response.
|
||||
1. Request without authorization will return error message:
|
||||
|
||||
HTTP/1.1 400 Bad Request
|
||||
Content-Length: 35
|
||||
{"error":"You need to sign in or sign up before continuing."}
|
||||
|
||||
{"message":"Problems parsing JSON"}
|
||||
2. Rate limit exceed will return this:
|
||||
|
||||
2. Sending the wrong type of JSON values will result in a `400 Bad
|
||||
Request` response.
|
||||
{"message":"403 Forbidden | Rate Limit Exceeded"}
|
||||
|
||||
HTTP/1.1 400 Bad Request
|
||||
Content-Length: 40
|
||||
3. Some requests can cause cancer of 404, 500 and 503 errors. In these situatins you will receive such data:
|
||||
|
||||
{"message":"Body should be a JSON Hash"}
|
||||
<%= json(:error_404) %>
|
||||
|
||||
3. Sending invalid fields will result in a `422 Unprocessable Entity`
|
||||
response.
|
||||
<%= json(:error_500) %>
|
||||
|
||||
HTTP/1.1 422 Unprocessable Entity
|
||||
Content-Length: 149
|
||||
<%= json(:error_503) %>
|
||||
|
||||
{
|
||||
"message": "Validation Failed",
|
||||
"errors": [
|
||||
{
|
||||
"resource": "Issue",
|
||||
"field": "title",
|
||||
"code": "missing_field"
|
||||
}
|
||||
]
|
||||
}
|
||||
<%= json(:error_401) %>
|
||||
|
||||
All error objects have resource and field properties so that your client
|
||||
can tell what the problem is. There's also an error code to let you
|
||||
know what is wrong with the field. These are the possible validation error
|
||||
codes:
|
||||
If you don't have enough rights for requested action, you will receive
|
||||
error response such this:
|
||||
|
||||
missing
|
||||
: This means a resource does not exist.
|
||||
<%= json(:error_403) %>
|
||||
|
||||
missing\_field
|
||||
: This means a required field on a resource has not been set.
|
||||
|
||||
invalid
|
||||
: This means the formatting of a field is invalid. The documentation
|
||||
for that resource should be able to give you more specific information.
|
||||
|
||||
already\_exists
|
||||
: This means another resource has the same value as this field. This
|
||||
can happen in resources that must have some unique key (such as Label
|
||||
names).
|
||||
|
||||
If resources have custom validation errors, they will be documented with
|
||||
the resource.
|
||||
and http status code will be 403.
|
||||
|
||||
## HTTP Verbs
|
||||
|
||||
Where possible, API v3 strives to use appropriate HTTP verbs for each
|
||||
Where possible, API v1 strives to use appropriate HTTP verbs for each
|
||||
action.
|
||||
|
||||
HEAD
|
||||
: Can be issued against any resource to get just the HTTP header info.
|
||||
|
||||
GET
|
||||
: Used for retrieving resources.
|
||||
|
||||
|
|
@ -124,13 +86,6 @@ POST
|
|||
: Used for creating resources, or performing custom actions (such as
|
||||
merging a pull request).
|
||||
|
||||
PATCH
|
||||
: Used for updating resources with partial JSON data. For instance, an
|
||||
Issue resource has `title` and `body` attributes. A PATCH request may
|
||||
accept one or more of the attributes to update the resource. PATCH is a
|
||||
relatively new and uncommon HTTP verb, so resource endpoints also accept
|
||||
POST requests.
|
||||
|
||||
PUT
|
||||
: Used for replacing resources or collections. For PUT requests
|
||||
with no `body` attribute, be sure to set the `Content-Length` header to zero.
|
||||
|
|
@ -140,33 +95,7 @@ DELETE
|
|||
|
||||
## Authentication
|
||||
|
||||
There are two ways to authenticate through GitHub API v3:
|
||||
|
||||
Basic Authentication:
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl -u "username" https://api.github.com
|
||||
</pre>
|
||||
|
||||
OAuth2 Token (sent in a header):
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
|
||||
</pre>
|
||||
|
||||
OAuth2 Token (sent as a parameter):
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl https://api.github.com/?access_token=OAUTH-TOKEN
|
||||
</pre>
|
||||
|
||||
Read [more about OAuth2](/v3/oauth/). Note that OAuth2 tokens can be [acquired
|
||||
programmatically](/v3/oauth/#create-a-new-authorization), for applications that
|
||||
are not websites.
|
||||
|
||||
Requests that require authentication will return 404, instead of 403, in some places.
|
||||
This is to prevent the accidental leakage of private repositories to unauthorized
|
||||
users.
|
||||
Sory, where is no authentication at the moment :(
|
||||
|
||||
## Pagination
|
||||
|
||||
|
|
@ -175,18 +104,15 @@ default. You can specify further pages with the `?page` parameter. For some
|
|||
resources, you can also set a custom page size up to 100 with the `?per_page` parameter.
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl https://api.github.com/user/repos?page=2&per_page=100
|
||||
$ curl https://abf.rosalinux.ru/api/v1/build_lists.json?page=2&per_page=100
|
||||
</pre>
|
||||
|
||||
The pagination info is included in [the Link
|
||||
header](http://www.w3.org/Protocols/9707-link-header.html). It is important to
|
||||
follow these Link header values instead of constructing your own URLs. In some
|
||||
instances, such as in the [Commits
|
||||
API](/v3/repos/commits/), pagination is based on
|
||||
SHA1 and not on page number.
|
||||
follow these Link header values instead of constructing your own URLs.
|
||||
|
||||
Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
|
||||
<https://api.github.com/user/repos?page=50&per_page=100>; rel="last"
|
||||
Link: <https://abf.rosalinux.ru/api/v1/build_lists.json?page=3&per_page=100>; rel="next",
|
||||
<https://abf.rosalinux.ru/build_lists.json?page=50&per_page=100>; rel="last"
|
||||
|
||||
_Linebreak is included for readability._
|
||||
|
||||
|
|
@ -211,166 +137,13 @@ login, your OAuth token, or request IP. You can check the returned HTTP
|
|||
headers of any API request to see your current status:
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl -i https://api.github.com/users/whatever
|
||||
$ curl -i https://abf.rosalinux.ru/whatever
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Status: 200 OK
|
||||
X-RateLimit-Limit: 5000
|
||||
X-RateLimit-Remaining: 4966
|
||||
X-RateLimit-Limit: 500
|
||||
X-RateLimit-Remaining: 496
|
||||
</pre>
|
||||
|
||||
You can also check your rate limit status without incurring an API hit.
|
||||
|
||||
GET /rate_limit
|
||||
|
||||
### Rate limit
|
||||
|
||||
<%= headers 200 %>
|
||||
<%= json :rate => {:remaining => 4999, :limit => 5000} %>
|
||||
|
||||
<br>
|
||||
|
||||
#### Unauthenticated rate limited requests
|
||||
|
||||
If you need to make unauthenticated calls but need to use a higher rate limit
|
||||
associated with your OAuth application, you can send over your client ID and
|
||||
secret in the query string.
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl -i https://api.github.com/users/whatever?client_id=xxxxxxxxxxxxxx&client_secret=yyyyyyyyyyyyyyyyyyyyy
|
||||
|
||||
HTTP/1.1 200 OK
|
||||
Status: 200 OK
|
||||
X-RateLimit-Limit: 12500
|
||||
X-RateLimit-Remaining: 11966
|
||||
</pre>
|
||||
|
||||
This method should only be used for server-to-server calls. You should never
|
||||
share your client secret with anyone or include it in client-side browser code.
|
||||
|
||||
Please [contact us](https://github.com/contact) to request white listed access
|
||||
for your application. We prefer sites that setup OAuth applications for their
|
||||
users.
|
||||
|
||||
## Conditional Requests
|
||||
|
||||
Most responses return `Last-Modified` and `Etag` headers. You can use the values
|
||||
of these headers to make subsequent requests to those resources using the
|
||||
`If-Modified-Since` and `If-None-Match` headers, respectively. If the resource
|
||||
has not changed, the server will return a `304 Not Modified`. Also note: making
|
||||
a conditional request and receiving a 304 response does not count against your
|
||||
[Rate Limit](#rate-limiting), so we encourage you to use it whenever possible.
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl -i https://api.github.com/user
|
||||
HTTP/1.1 200 OK
|
||||
Cache-Control: private, max-age=60
|
||||
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
|
||||
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
|
||||
Status: 200 OK
|
||||
Vary: Accept, Authorization, Cookie
|
||||
X-RateLimit-Limit: 5000
|
||||
X-RateLimit-Remaining: 4996
|
||||
|
||||
$ curl -i https://api.github.com/user -H "If-Modified-Since: Thu, 05 Jul 2012 15:31:30 GMT"
|
||||
HTTP/1.1 304 Not Modified
|
||||
Cache-Control: private, max-age=60
|
||||
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
|
||||
Status: 304 Not Modified
|
||||
Vary: Accept, Authorization, Cookie
|
||||
X-RateLimit-Limit: 5000
|
||||
X-RateLimit-Remaining: 4996
|
||||
|
||||
$ curl -i https://api.github.com/user -H 'If-None-Match: "644b5b0155e6404a9cc4bd9d8b1ae730"'
|
||||
HTTP/1.1 304 Not Modified
|
||||
Cache-Control: private, max-age=60
|
||||
ETag: "644b5b0155e6404a9cc4bd9d8b1ae730"
|
||||
Last-Modified: Thu, 05 Jul 2012 15:31:30 GMT
|
||||
Status: 304 Not Modified
|
||||
Vary: Accept, Authorization, Cookie
|
||||
X-RateLimit-Limit: 5000
|
||||
X-RateLimit-Remaining: 4996
|
||||
</pre>
|
||||
|
||||
## Cross Origin Resource Sharing
|
||||
|
||||
The API supports Cross Origin Resource Sharing (CORS) for AJAX requests.
|
||||
you can read the [CORS W3C working draft](http://www.w3.org/TR/cors), or
|
||||
[this intro](http://code.google.com/p/html5security/wiki/CrossOriginRequestSecurity) from the
|
||||
HTML 5 Security Guide.
|
||||
|
||||
Here's a sample request sent from a browser hitting
|
||||
`http://some-site.com`:
|
||||
|
||||
$ curl -i https://api.github.com -H "Origin: http://some-site.com"
|
||||
HTTP/1.1 302 Found
|
||||
|
||||
Any domain that is registered as an OAuth Application is accepted.
|
||||
Here's a sample request for a browser hitting [Calendar About Nothing](http://calendaraboutnothing.com/):
|
||||
|
||||
$ curl -i https://api.github.com -H "Origin: http://calendaraboutnothing.com"
|
||||
HTTP/1.1 302 Found
|
||||
Access-Control-Allow-Origin: http://calendaraboutnothing.com
|
||||
Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
|
||||
Access-Control-Allow-Credentials: true
|
||||
|
||||
This is what the CORS preflight request looks like:
|
||||
|
||||
$ curl -i https://api.github.com -H "Origin: http://calendaraboutnothing.com" -X OPTIONS
|
||||
HTTP/1.1 204 No Content
|
||||
Access-Control-Allow-Origin: http://calendaraboutnothing.com
|
||||
Access-Control-Allow-Headers: Authorization, X-Requested-With
|
||||
Access-Control-Allow-Methods: GET, POST, PATCH, PUT, DELETE
|
||||
Access-Control-Expose-Headers: Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-OAuth-Scopes, X-Accepted-OAuth-Scopes
|
||||
Access-Control-Max-Age: 86400
|
||||
Access-Control-Allow-Credentials: true
|
||||
|
||||
## JSON-P Callbacks
|
||||
|
||||
You can send a `?callback` parameter to any GET call to have the results
|
||||
wrapped in a JSON function. This is typically used when browsers want
|
||||
to embed GitHub content in web pages by getting around cross domain
|
||||
issues. The response includes the same data output as the regular API,
|
||||
plus the relevant HTTP Header information.
|
||||
|
||||
<pre class="terminal">
|
||||
$ curl https://api.github.com?callback=foo
|
||||
|
||||
foo({
|
||||
"meta": {
|
||||
"status": 200,
|
||||
"X-RateLimit-Limit": "5000",
|
||||
"X-RateLimit-Remaining": "4966",
|
||||
"Link": [ // pagination headers and other links
|
||||
["https://api.github.com?page=2", {"rel": "next"}]
|
||||
]
|
||||
},
|
||||
"data": {
|
||||
// the data
|
||||
}
|
||||
})
|
||||
</pre>
|
||||
|
||||
You can write a javascript handler to process the callback like this:
|
||||
|
||||
<pre class="highlight"><code class="language-javascript">function foo(response) {
|
||||
var meta = response.meta
|
||||
var data = response.data
|
||||
console.log(meta)
|
||||
console.log(data)
|
||||
}</code></pre>
|
||||
|
||||
All of the headers are the same String value as the HTTP Headers with one
|
||||
notable exception: Link. Link headers are pre-parsed for you and come
|
||||
through as an array of `[url, options]` tuples.
|
||||
|
||||
A link that looks like this:
|
||||
|
||||
Link: <url1>; rel="next", <url2>; rel="foo"; bar="baz"
|
||||
|
||||
... will look like this in the Callback output:
|
||||
|
||||
<%= json "Link" => [
|
||||
["url1", {:rel => "next"}],
|
||||
["url2", {:rel => "foo", :bar => "baz"}]] %>
|
||||
|
||||
|
|
|
|||
|
|
@ -9,7 +9,6 @@ title: Project Build | GitHub API
|
|||
* <a href="#reject-publish-build-task">Reject publish build task</a>
|
||||
* <a href="#search">Search</a>
|
||||
* <a href="#destroy-build-task">Destroy build task</a>
|
||||
* <a href="#and-401-errors">404, 500, 503 and 401 errors</a>
|
||||
|
||||
## 1. Show build data
|
||||
|
||||
|
|
@ -183,21 +182,3 @@ EXAMPLES OF RESPONSES:
|
|||
|
||||
You can't destroy build list. Only cancel it. :)
|
||||
|
||||
## 8. 404, 500, 503 and 401 errors.
|
||||
|
||||
Some requests can cause cancer of 404, 500 and 503 errors. In these situatins you will receive such data:
|
||||
|
||||
<%= json(:error_404) %>
|
||||
|
||||
<%= json(:error_500) %>
|
||||
|
||||
<%= json(:error_503) %>
|
||||
|
||||
<%= json(:error_401) %>
|
||||
|
||||
If you don't have enough rights for requested action, you will receive
|
||||
error response such this:
|
||||
|
||||
<%= json(:error_403) %>
|
||||
|
||||
and http status code will be 403.
|
||||
|
|
|
|||
|
|
@ -42,7 +42,6 @@
|
|||
<li><a href="/v1/build#reject-publish-build-task">Reject publish build task</a></li>
|
||||
<li><a href="/v1/build#search">Search</a></li>
|
||||
<li><a href="/v1/build#destroy-build-task">Destroy build task</a></li>
|
||||
<li><a href="/v1/build#and-401-errors">404, 500, 503 and 401 errors</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li class="js-topic">
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
class Rack::Throttle::Limiter
|
||||
def http_error(code, message = nil, headers = {})
|
||||
[code, {'Content-Type' => 'application/json; charset=utf-8'}.merge(headers),
|
||||
Array(({'message' => http_status(code) + " | " + message}.to_json))]
|
||||
end
|
||||
end
|
||||
|
||||
Loading…
Reference in New Issue