From 87d40fd276ade536e0b6b3019e52c2e1844e47ea Mon Sep 17 00:00:00 2001
From: Alex Denisov <1101.debian@gmail.com>
Date: Sun, 16 Sep 2012 18:21:59 +0300
Subject: [PATCH] Docs added

---
 doc/api/README.md                  |  1 +
 doc/api/keys.md                    | 79 ++++++++++++++++++++++++++++++
 lib/api/keys.rb                    |  8 +++
 spec/requests/api/ssh_keys_spec.rb | 18 +++++++
 4 files changed, 106 insertions(+)
 create mode 100644 doc/api/keys.md

diff --git a/doc/api/README.md b/doc/api/README.md
index 93919b4285..9741072c09 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -34,3 +34,4 @@ When listing resources you can pass the following parameters:
 + [Snippets](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/snippets.md)
 + [Issues](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/issues.md)
 + [Milestones](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/milestones.md)
++ [SSH Keys](https://github.com/gitlabhq/gitlabhq/blob/master/doc/api/keys.md)
diff --git a/doc/api/keys.md b/doc/api/keys.md
new file mode 100644
index 0000000000..8106eb8abb
--- /dev/null
+++ b/doc/api/keys.md
@@ -0,0 +1,79 @@
+## List keys
+
+Get a list of currently authenticated user's keys.
+
+```
+GET /keys
+```
+
+```json
+[
+  {
+    "id": 1,
+    "title" : "Public key"
+    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
+      596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
+      soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
+  },
+  {
+    "id": 3,
+    "title" : "Another Public key"
+    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
+      596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
+      soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
+  }
+]
+```
+
+## Single key
+
+Get a single key.
+
+```
+GET /keys/:id
+```
+
+Parameters:
+
++ `id` (required) - The ID of a key
+
+```json
+{
+  "id": 1,
+  "title" : "Public key"
+  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4
+      596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4
+      soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
+  }
+```
+## Add key
+
+Create new key owned by currently authenticated user
+
+```
+POST /keys
+```
+
+Parameters:
+
++ `title` (required) - new SSH Key
++ `key` (optional) - new SSH key's title
+
+Will return created key with status `201 Created` on success, or `404 Not
+found` on fail.
+
+## Delete key
+
+Delete key owned by currently authenticated user
+
+```
+DELETE /keys/:id
+```
+
+Parameters:
+
++ `id` (required) - key ID
+
+Will return `200 OK` on success, or `404 Not Found` on fail.
+
+
diff --git a/lib/api/keys.rb b/lib/api/keys.rb
index 96ab7029fe..d58c7caf5c 100644
--- a/lib/api/keys.rb
+++ b/lib/api/keys.rb
@@ -10,6 +10,14 @@ module Gitlab
       get do
         present current_user.keys, with: Entities::Key
       end
+      # Get single key owned by currently authenticated user
+      #
+      # Example Request:
+      #   GET /keys/:id
+      get "/:id" do
+        key = current_user.keys.find params[:id]
+        present key, with: Entities::Key
+      end
       # Add new ssh key to currently authenticated user
       # 
       # Parameters:
diff --git a/spec/requests/api/ssh_keys_spec.rb b/spec/requests/api/ssh_keys_spec.rb
index b8c6037789..7fb8c920fb 100644
--- a/spec/requests/api/ssh_keys_spec.rb
+++ b/spec/requests/api/ssh_keys_spec.rb
@@ -28,6 +28,20 @@ describe Gitlab::Keys do
     end
   end
 
+  describe "GET /keys/:id" do
+    it "should returm single key" do
+      user.keys << key
+      user.save
+      get api("/keys/#{key.id}", user)
+      response.status.should == 200
+      json_response["title"].should == key.title
+    end
+    it "should return 404 Not Found within invalid ID" do
+      get api("/keys/42", user)
+      response.status.should == 404
+    end
+  end
+
   describe "POST /keys" do
     it "should not create invalid ssh key" do
       post api("/keys", user), { title: "invalid key" }
@@ -49,6 +63,10 @@ describe Gitlab::Keys do
         delete api("/keys/#{key.id}", user)
       }.to change{user.keys.count}.by(-1)
     end
+    it "should return 404 Not Found within invalid ID" do
+      delete api("/keys/42", user)
+      response.status.should == 404
+    end
   end
 
 end
-- 
2.30.9