From f7d28dd23c5c626f09a131c176c7ebf407b6bd2e Mon Sep 17 00:00:00 2001 From: "konstantin.grabar" Date: Wed, 19 Sep 2012 19:02:49 +0400 Subject: [PATCH] [refs #374] Patch Rack::Throttle http_error method. Finish main page text --- apidocs/content/index.md | 285 +++------------------------ apidocs/content/v1/build.md | 19 -- apidocs/layouts/default.html | 1 - config/initializers/rack_throttle.rb | 7 + 4 files changed, 36 insertions(+), 276 deletions(-) create mode 100644 config/initializers/rack_throttle.rb diff --git a/apidocs/content/index.md b/apidocs/content/index.md index 711e68fe6..035234feb 100644 --- a/apidocs/content/index.md +++ b/apidocs/content/index.md @@ -16,18 +16,14 @@ All of the urls in this manual have the same tail: .json. Because the default * Authentication * Pagination * Rate Limiting -* Conditional Requests -* Cross Origin Resource Sharing -* JSON-P Callbacks ## 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. 
-$ 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
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: - -
-$ curl -u "username" https://api.github.com
-
- -OAuth2 Token (sent in a header): - -
-$ curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
-
- -OAuth2 Token (sent as a parameter): - -
-$ curl https://api.github.com/?access_token=OAUTH-TOKEN
-
- -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. 
-$ 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
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: ; rel="next", - ; rel="last" + Link: ; rel="next", + ; 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: 
-$ 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
-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} %> -
-#### 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. - -
-$ 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
-
- -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. - -
-$ 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
-
- -## 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. - -
-$ 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
-  }
-})
-
- -You can write a javascript handler to process the callback like this: - -
function foo(response) {
-  var meta = response.meta
-  var data = response.data
-  console.log(meta)
-  console.log(data)
-}
- -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: ; rel="next", ; rel="foo"; bar="baz" - -... will look like this in the Callback output: - -<%= json "Link" => [ - ["url1", {:rel => "next"}], - ["url2", {:rel => "foo", :bar => "baz"}]] %> - diff --git a/apidocs/content/v1/build.md b/apidocs/content/v1/build.md index cc00afcaf..b71ff83da 100644 --- a/apidocs/content/v1/build.md +++ b/apidocs/content/v1/build.md @@ -9,7 +9,6 @@ title: Project Build | GitHub API * Reject publish build task * Search * Destroy build task -* 404, 500, 503 and 401 errors ## 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. diff --git a/apidocs/layouts/default.html b/apidocs/layouts/default.html index 1348d9dcd..6fd967344 100644 --- a/apidocs/layouts/default.html +++ b/apidocs/layouts/default.html @@ -42,7 +42,6 @@
  • Reject publish build task
  • Search
  • Destroy build task
    • -
  • 404, 500, 503 and 401 errors
  • diff --git a/config/initializers/rack_throttle.rb b/config/initializers/rack_throttle.rb new file mode 100644 index 000000000..dc0572042 --- /dev/null +++ b/config/initializers/rack_throttle.rb @@ -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 +