[refs #374] Add top links, titles and request styles. Add index text

apidocs/content/index.md

@@ -9,3 +9,368 @@ This describes the resources that make up the official Rosa ABF API. If you have
 **Note: This API is in a beta state. Breaking changes may occur.**
 
 All of the urls in this manual have the same tail: .json. Because the default
+
+* <a href="#schema">Schema</a>
+* <a href="#client-errors">Client Errors</a>
+* <a href="#http-verbs">HTTP Verbs</a>
+* <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
+sent and received as JSON.
+
+<pre class="terminal">
+$ curl -i https://api.github.com
+
+HTTP/1.1 302 Found
+Server: nginx/1.0.12
+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
+Content-Length: 0
+
+</pre>
+
+Blank fields are included as `null` instead of being omitted.
+
+All timestamps are returned in ISO 8601 format:
+
+    YYYY-MM-DDTHH:MM:SSZ
+
+## 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.
+
+        HTTP/1.1 400 Bad Request
+        Content-Length: 35
+
+        {"message":"Problems parsing JSON"}
+
+2. Sending the wrong type of JSON values will result in a `400 Bad
+   Request` response.
+
+        HTTP/1.1 400 Bad Request
+        Content-Length: 40
+
+        {"message":"Body should be a JSON Hash"}
+
+3. Sending invalid fields will result in a `422 Unprocessable Entity`
+   response.
+
+        HTTP/1.1 422 Unprocessable Entity
+        Content-Length: 149
+
+        {
+          "message": "Validation Failed",
+          "errors": [
+            {
+              "resource": "Issue",
+              "field": "title",
+              "code": "missing_field"
+            }
+          ]
+        }
+
+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:
+
+missing
+: This means a resource does not exist.
+
+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.
+
+## HTTP Verbs
+
+Where possible, API v3 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.
+
+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.
+
+DELETE
+: Used for deleting resources.
+
+## 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.
+
+## Pagination
+
+Requests that return multiple items will be paginated to 30 items by
+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
+</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.
+
+    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"
+
+_Linebreak is included for readability._
+
+The possible `rel` values are:
+
+`next`
+: Shows the URL of the immediate next page of results.
+
+`last`
+: Shows the URL of the last page of results.
+
+`first`
+: Shows the URL of the first page of results.
+
+`prev`
+: Shows the URL of the immediate previous page of results.
+
+## Rate Limiting
+
+We limit requests to API v3 to 5000 per hour.  This is keyed off either your
+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
+
+HTTP/1.1 200 OK
+Status: 200 OK
+X-RateLimit-Limit: 5000
+X-RateLimit-Remaining: 4966
+</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/architectures.md

@@ -1,8 +1,12 @@
-### 4. Architectures list
+---
+title: Architectures | GitHub API
+---
+
+### 1. Architectures list
 
 This request will return you all needed data about posible architectures into JSON format.
 
-URL: /api/v1/arches.json
+URL: : /api/v1/arches.json
 
 TYPE: GET
 

apidocs/content/v1/build.md

@@ -2,14 +2,24 @@
 title: Project Build | GitHub API
 ---
 
+* <a href="#show-build-data">Show build data</a>
+* <a href="#create-build-task">Create build task</a>
+* <a href="#cancel-build-task">Cancel build task</a>
+* <a href="#publish-build-task">Publish build task</a>
+* <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
 
 This request will return you all needed data of requested build task into JSON format.
 
-URL: /buils_lists/:id.json
+URL:
 
-TYPE: GET
+    GET /buils_lists/:id.json
 
+&nbsp;
 PARAMS:
 : * :id - identifier of current build task
 
@@ -34,14 +44,14 @@ Create parameters:
 POSIBLE UPDATE TYPES:
 
     security
-    bugfix 
-    enhancement 
-    recommended 
+    bugfix
+    enhancement
+    recommended
     newpackage
 
-URL: /api/v1/build_lists.json
+URL:
 
-TYPE: POST
+    POST /api/v1/build_lists.json
 
 REQUEST EXAMPLE:
 
@@ -59,9 +69,9 @@ RESPONSE EXAMPLE:
 
 By this request you can cancel build task.
 
-URL: /buils_lists/:id/cancel.json
+URL:
 
-TYPE: PUT
+    PUT /buils_lists/:id/cancel.json
 
 RESPONSE:
 
@@ -78,9 +88,9 @@ EXAMPLE:
 
 By this request you can publish build task.
 
-URL: /buils_lists/:id/publish.json
+URL:
 
-TYPE: PUT
+    PUT /buils_lists/:id/publish.json
 
 RESPONSE:
 
@@ -97,9 +107,9 @@ EXAMPLE:
 
 By this request you can reject publish build task.
 
-URL: /buils_lists/:id/reject_publish.json
+URL:
 
-TYPE: PUT
+    PUT /buils_lists/:id/reject_publish.json
 
 RESPONSE:
 
@@ -151,9 +161,9 @@ BUILD LIST POSIBLE STATUSES
         Project not found: 3
         Project version not found: 4
 
-URL: /build_lists.json?<search params>
+URL:
 
-TYPE: GET
+    GET /build_lists.json?<search params>
 
 RESPONSE:
 

apidocs/content/v1/platforms.md

@@ -1,6 +1,13 @@
-## 3. Platform
+---
+title: Platforms | GitHub API
+---
 
-### 3.1. Platform data
+* <a href="#platform-data">Platform data</a>
+* <a href="#platform-list">Platform list</a>
+
+## 1. Platforms
+
+### 1.1. Platform data
 
 This request will return you all needed data about platforms list into JSON format.
 
@@ -20,7 +27,7 @@ EXAMPLE:
 
 <%= json(:platform_data_response_example) %>
 
-### 3.2. Platform list
+### 1.2. Platform list
 
 This request will return you all needed data about platform into JSON format.
 

apidocs/content/v1/projects.md

@@ -1,3 +1,10 @@
+---
+title: Projects | GitHub API
+---
+
+* <a href="#project-data">Project data</a>
+* <a href="#project-id-get-by-name-and-owner">Project id get by name and owner</a>
+
 ## 1. Projects
 
 ### 1.1. Project data

apidocs/content/v1/repositories.md

@@ -1,6 +1,10 @@
-## 2. Repository
+---
+title: Platforms | GitHub API
+---
 
-### 2.1. Repository data
+## 1. Repositories
+
+### 1.1. Repository data
 
 This request will return you all needed data about repositories list into JSON format.
 

apidocs/layouts/default.html

@@ -46,15 +46,15 @@
             </ul>
           </li>
           <li class="js-topic">
-            <h3><a href="/v1/platforms/" class="js-expand-btn collapsed">&nbsp;</a><a href="/">Platforms</a></h3>
+            <h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v1/platforms/">Platforms</a></h3>
             <ul class="js-guides">
               <li><a href="/v1/platforms#platform-data">Platform data</a></li>
               <li><a href="/v1/platforms#platform-list">Platform list</a></li>
             </ul>
           </li>
-            <h3><a href="/v1/repositories/">Repositories</a></h3>
+          <h3><a href="/v1/repositories/">Repositories</a></h3>
           <li class="js-topic">
-            <h3><a href="/v1/projects" class="js-expand-btn collapsed">&nbsp;</a><a href="/">Projects</a></h3>
+            <h3><a href="#" class="js-expand-btn collapsed">&nbsp;</a><a href="/v1/projects">Projects</a></h3>
             <ul class="js-guides">
               <li><a href="/v1/projects#project-data">Project data</a></li>
               <li><a href="/v1/projects#project-id-get-by-name-and-owner">Project id get by name and owner</a></li>