Adding further documentation and corrections on builds and runners

4 files changed, 70 insertions, 15 deletions

diff --git a/doc/api.md b/doc/api.md
index 6681478..1472918 100644
--- a/doc/api.md
+++ b/doc/api.md
@@ -30,6 +30,8 @@ Lists all projects that the authenticated user has access to.
 GET /projects
 ```
 
+Returns:
+
 ```json
     [
   {
@@ -71,6 +73,8 @@ Lists all projects that the authenticated user owns.
 GET /projects/owned
 ```
 
+Returns:
+
 ```json
 [
   {
@@ -168,8 +172,58 @@ Parameters:
 
 ## Runners
 
-TBA
+### Register a new runner
+
+Used to make Gitlab CI aware of available runners.
+
+    POST /runners/register
+
+Parameters:
+
+  * `token` (required) - The unique token of runner
+  * `public_key` (required) - Deploy key used to get projects
+
+Returns:
+
+```json
+{
+  "id" : 85,
+  "token" : "12b68e90394084703135"
+}
+```
 
 ## Builds
 
-TBA
+### Runs oldest pending build by runner
+
+    POST /builds/register
+
+Parameters:
+
+  * `token` (required) - The unique token of runner
+
+Returns:
+
+```json
+{
+  "id" : 79,
+  "commands" : "",
+  "path" : "",
+  "ref" : "",
+  "sha" : "",
+  "project_id" : 6,
+  "repo_url" : "git@demo.gitlab.com:gitlab/gitlab-shell.git",
+  "before_sha" : ""
+}
+```
+
+
+### Update details of an existing build
+
+    PUT /builds/:id
+
+Parameters:
+
+  * `id` (required) - The ID of a project
+  * `state` (optional) - The state of a build
+  * `trace` (optional) - The trace of a build
diff --git a/lib/api/builds.rb b/lib/api/builds.rb
index 75ae4e0..3b70a88 100644
--- a/lib/api/builds.rb
+++ b/lib/api/builds.rb
@@ -1,10 +1,10 @@
 module API
-  # Issues API
+  # Builds API
   class Builds < Grape::API
     resource :builds do
-      before { authenticate_runner!}
+      before { authenticate_runner! }
 
-      # Register a build by runner
+      # Runs oldest pending build by runner
       #
       # Parameters:
       #   token (required) - The uniq token of runner
@@ -28,7 +28,7 @@ module API
       # Parameters:
       #   id (required) - The ID of a project
       #   state (optional) - The state of a build
-      #   output (optional) - The trace of a build
+      #   trace (optional) - The trace of a build
       # Example Request:
       #   PUT /builds/:id
       put ":id" do
diff --git a/lib/api/helpers.rb b/lib/api/helpers.rb
index 13719b4..4bea5a2 100644
--- a/lib/api/helpers.rb
+++ b/lib/api/helpers.rb
@@ -13,6 +13,10 @@ module API
       end
     end
 
+    def current_runner
+      @runner ||= Runner.find_by_token(params[:token])
+    end
+
     def authenticate!
       forbidden! unless current_user
     end
@@ -25,10 +29,6 @@ module API
       forbidden! unless current_runner
     end
 
-    def current_runner
-      @runner ||= Runner.find_by_token(params[:token])
-    end
-
     # Checks the occurrences of required attributes, each attribute must be present in the params hash
     # or a Bad Request error is invoked.
     #
diff --git a/lib/api/runners.rb b/lib/api/runners.rb
index ee7b343..8bf2370 100644
--- a/lib/api/runners.rb
+++ b/lib/api/runners.rb
@@ -1,16 +1,17 @@
 module API
-  # Issues API
+  # Runners API
   class Runners < Grape::API
     resource :runners do
-      before { authenticate_runners!}
+      before { authenticate_runners! }
 
-      # Register a build by runner
+      # Register a new runner
       #
       # Parameters:
-      #   token (required) - The uniq token of runner
+      #   token (required) - The unique token of runner
+      #   public_key (required) - Deploy key used to get projects
       #
       # Example Request:
-      #   POST /builds/register
+      #   POST /runners/register
       post "register" do
         required_attributes! [:token, :public_key]