[refs #374] Patch Rack::Throttle http_error method. Finish main page

text

apidocs/content/index.md

@@ -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`
+All API access is over HTTPS and all data is
-domain (or through `yourdomain.com/api/v3/` for enterprise).  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
+X-RateLimit-Limit: 500
-ETag: "d41d8cd98f00b204e9800998ecf8427e"
+Location: http://abf.rosalinux.ru
-Location: http://developer.github.com
+X-RateLimit-Remaining: 499
-X-RateLimit-Remaining: 4999
 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
+  {"error":"You need to sign in or sign up before continuing."}
-        Content-Length: 35
 
-        {"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
+  {"message":"403 Forbidden | Rate Limit Exceeded"}
-   Request` response.
 
-        HTTP/1.1 400 Bad Request
+3. Some requests can cause cancer of 404, 500 and 503 errors. In these situatins you will receive such data:
-        Content-Length: 40
 
-        {"message":"Body should be a JSON Hash"}
+<%= json(:error_404) %>
 
-3. Sending invalid fields will result in a `422 Unprocessable Entity`
+<%= json(:error_500) %>
-   response.
 
-        HTTP/1.1 422 Unprocessable Entity
+<%= json(:error_503) %>
-        Content-Length: 149
 
-        {
+<%= json(:error_401) %>
-          "message": "Validation Failed",
-          "errors": [
-            {
-              "resource": "Issue",
-              "field": "title",
-              "code": "missing_field"
-            }
-          ]
-        }
 
-All error objects have resource and field properties so that your client
+If you don't have enough rights for requested action, you will receive
-can tell what the problem is.  There's also an error code to let you
+error response such this:
-know what is wrong with the field.  These are the possible validation error
-codes:
 
-missing
+<%= json(:error_403) %>
-: This means a resource does not exist.
 
-missing\_field
+and http status code will be 403.
-: 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.
 
 ## 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:
+Sory, where is no authentication at the moment :(
-
-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.
 
 ## 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
+follow these Link header values instead of constructing your own URLs.
-instances, such as in the [Commits
-API](/v3/repos/commits/), pagination is based on
-SHA1 and not on page number.
 
-    Link: <https://api.github.com/user/repos?page=3&per_page=100>; rel="next",
+    Link: <https://abf.rosalinux.ru/api/v1/build_lists.json?page=3&per_page=100>; rel="next",
-      <https://api.github.com/user/repos?page=50&per_page=100>; rel="last"
+      <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-Limit: 500
-X-RateLimit-Remaining: 4966
+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"}]] %>
-

apidocs/content/v1/build.md

@@ -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.

apidocs/layouts/default.html

@@ -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">

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
+