From 9ee6c58accfd51036d7242dc51fbfec2c9abeb06 Mon Sep 17 00:00:00 2001
From: Sebastian Ziebell <sebastian.ziebell@asquera.de>
Date: Thu, 21 Feb 2013 21:13:46 +0100
Subject: [PATCH] API documentation updated for project snippets.

The API Documentation for project snippets got infos to return codes. Tests are added
to check status codes when handling project snippets.
---
 doc/api/snippets.md                | 71 ++++++++++++++++++++++--------
 spec/requests/api/projects_spec.rb | 11 +++++
 2 files changed, 64 insertions(+), 18 deletions(-)

diff --git a/doc/api/snippets.md b/doc/api/snippets.md
index ceb8a63d..61dbb5e4 100644
--- a/doc/api/snippets.md
+++ b/doc/api/snippets.md
@@ -10,9 +10,15 @@ Parameters:
 
 + `id` (required) - The ID of a project
 
+Return values:
+
++ `200 Ok` on success and a list of project snippets
++ `401 Unauthorized` if user is not authenticated
+
+
 ## Single snippet
 
-Get a project snippet.
+Get a single project snippet.
 
 ```
 GET /projects/:id/snippets/:snippet_id
@@ -42,22 +48,16 @@ Parameters:
 }
 ```
 
-## Snippet content
+Return values:
 
-Get a raw project snippet.
++ `200 Ok` on success and the project snippet
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if snippet ID not found
 
-```
-GET /projects/:id/snippets/:snippet_id/raw
-```
 
-Parameters:
+## Create new snippet
 
-+ `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a project's snippet
-
-## New snippet
-
-Create a new project snippet.
+Creates a new project snippet.
 
 ```
 POST /projects/:id/snippets
@@ -71,11 +71,17 @@ Parameters:
 + `lifetime` (optional) - The expiration date of a snippet
 + `code` (required) - The content of a snippet
 
-Will return created snippet with status `201 Created` on success, or `404 Not found` on fail.
+Return values:
+
++ `201 Created` if snippet was successfully created and the snippet as JSON payload
++ `400 Bad Request` if one of the required attributes is not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
 
 ## Edit snippet
 
-Update an existing project snippet.
+Updates an existing project snippet.
 
 ```
 PUT /projects/:id/snippets/:snippet_id
@@ -90,11 +96,17 @@ Parameters:
 + `lifetime` (optional) - The expiration date of a snippet
 + `code` (optional) - The content of a snippet
 
-Will return updated snippet with status `200 OK` on success, or `404 Not found` on fail.
+Return values:
+
++ `200 Ok` on success and the updated project snippet
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
 
 ## Delete snippet
 
-Delete existing project snippet.
+Deletes an existing project snippet. This is an idempotent function and deleting a non-existent
+snippet still returns a `200 Ok` status code.
 
 ```
 DELETE /projects/:id/snippets/:snippet_id
@@ -105,5 +117,28 @@ Parameters:
 + `id` (required) - The ID of a project
 + `snippet_id` (required) - The ID of a project's snippet
 
-Status code `200` will be returned on success.
+Return values:
 
++ `200 Ok` on success and if the snippet was deleted its content
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID not found
+
+
+## Snippet content
+
+Get a raw project snippet.
+
+```
+GET /projects/:id/snippets/:snippet_id/raw
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `snippet_id` (required) - The ID of a project's snippet
+
+Return values:
+
++ `200 Ok` on success and the raw snippet
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if project ID or snippet ID is not found
\ No newline at end of file
diff --git a/spec/requests/api/projects_spec.rb b/spec/requests/api/projects_spec.rb
index 07a777d0..8ab7d825 100644
--- a/spec/requests/api/projects_spec.rb
+++ b/spec/requests/api/projects_spec.rb
@@ -480,6 +480,11 @@ describe Gitlab::API do
       json_response.should be_an Array
       json_response.first['title'].should == snippet.title
     end
+
+    it "should return 401 error if user not authenticated" do
+      get api("/projects/#{project.id}/snippets")
+      response.status.should == 401
+    end
   end
 
   describe "GET /projects/:id/snippets/:snippet_id" do
@@ -520,6 +525,12 @@ describe Gitlab::API do
         title: 'api test', file_name: 'sample.rb'
       response.status.should == 400
     end
+
+    it "should return a 401 error if user not authenticated" do
+      post api("/projects/#{project.id}/snippets"),
+        title: 'api test', file_name: 'sample.rb', code: 'i=0'
+      response.status.should == 401
+    end
   end
 
   describe "PUT /projects/:id/snippets/:shippet_id" do