API: groups documentation updated, functions return different status codes

Updates the API documentation of groups with infos to return codes. The function calls in the groups API have updated documentation and return `400 Bad Request` status code if a required attribute is missing.

API: groups documentation updated, functions return different status codes
Updates the API documentation of groups with infos to return codes. The function calls in the groups API have updated documentation and return `400 Bad Request` status code if a required attribute is missing.
Sebastian Ziebell
1 parent e119b0a0
Showing 3 changed files with 44 additions and 7 deletions Show diff stats
doc/api/groups.md
lib/api/groups.rb
spec/requests/api/groups_spec.rb
@@ -17,7 +17,14 @@ GET /groups
 ]
 ```
  
-## Details of group
+Return values:
+
++ `200 Ok` on success and list of groups
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if something fails
+
+
+## Details of a group
  
 Get all details of a group.
  
@@ -29,17 +36,30 @@ Parameters:
  
 + `id` (required) - The ID of a group
  
+Return values:
+
++ `200 Ok` on success and the details of a group
++ `401 Unauthorized` if user not authenticated
++ `404 Not Found` if group ID not found
+
+
 ## New group
  
-Create a new project group. Available only for admin
+Creates a new project group. Available only for admin.
  
 ```
 POST /groups
 ```
  
 Parameters:
-+ `name` (required)                  - Email
-+ `path`                             - Password
  
-Will return created group with status `201 Created` on success, or `404 Not found` on fail.
++ `name` (required) - The name of the group
++ `path` (required) - The path of the group
+
+Return valueS:
+
++ `201 Created` on success and the newly created group
++ `400 Bad Request` if one of the required attributes not given
++ `401 Unauthorized` if user is not authenticated
++ `404 Not Found` if something fails
  
@@ -6,6 +6,9 @@ module Gitlab
     resource :groups do
       # Get a groups list
       #
+      # Parameters
+      #   page (optional) - The page number of the groups list
+      #   per_page (optional) - The number of elements per page
       # Example Request:
       #  GET /groups
       get do
@@ -20,12 +23,16 @@ module Gitlab
       # Create group. Available only for admin
       #
       # Parameters:
-      #   name (required)                   - Name
-      #   path (required)                   - Path
+      #   name (required) - The name of the group
+      #   path (required) - The path of the group
       # Example Request:
       #   POST /groups
       post do
         authenticated_as_admin!
+
+        bad_request!(:name) unless params[:name].present?
+        bad_request!(:path) unless params[:path].present?
+
         attrs = attributes_for_keys [:name, :path]
         @group = Group.new(attrs)
         @group.owner = current_user
@@ -88,6 +88,16 @@ describe Gitlab::API do
         post api("/groups", admin), {:name => "Duplicate Test", :path => group2.path}
         response.status.should == 404
       end
+
+      it "should return 400 bad request error if name not given" do
+        post api("/groups", admin), { :path => group2.path }
+        response.status.should == 400
+      end
+
+      it "should return 400 bad request error if path not given" do
+        post api("/groups", admin), { :name => 'test' }
+        response.status.should == 400
+      end
     end
   end
 end
...	...	@@ -17,7 +17,14 @@ GET /groups
17	17	]
18	18	```
19	19
20		-## Details of group
	20	+Return values:
	21	+
	22	++ `200 Ok` on success and list of groups
	23	++ `401 Unauthorized` if user is not authenticated
	24	++ `404 Not Found` if something fails
	25	+
	26	+
	27	+## Details of a group
21	28
22	29	Get all details of a group.
23	30
...	...	@@ -29,17 +36,30 @@ Parameters:
29	36
30	37	+ `id` (required) - The ID of a group
31	38
	39	+Return values:
	40	+
	41	++ `200 Ok` on success and the details of a group
	42	++ `401 Unauthorized` if user not authenticated
	43	++ `404 Not Found` if group ID not found
	44	+
	45	+
32	46	## New group
33	47
34		-Create a new project group. Available only for admin
	48	+Creates a new project group. Available only for admin.
35	49
36	50	```
37	51	POST /groups
38	52	```
39	53
40	54	Parameters:
41		-+ `name` (required) - Email
42		-+ `path` - Password
43	55
44		-Will return created group with status `201 Created` on success, or `404 Not found` on fail.
	56	++ `name` (required) - The name of the group
	57	++ `path` (required) - The path of the group
	58	+
	59	+Return valueS:
	60	+
	61	++ `201 Created` on success and the newly created group
	62	++ `400 Bad Request` if one of the required attributes not given
	63	++ `401 Unauthorized` if user is not authenticated
	64	++ `404 Not Found` if something fails
45	65
...	...
...	...	@@ -6,6 +6,9 @@ module Gitlab
6	6	resource :groups do
7	7	# Get a groups list
8	8	#
	9	+ # Parameters
	10	+ # page (optional) - The page number of the groups list
	11	+ # per_page (optional) - The number of elements per page
9	12	# Example Request:
10	13	# GET /groups
11	14	get do
...	...	@@ -20,12 +23,16 @@ module Gitlab
20	23	# Create group. Available only for admin
21	24	#
22	25	# Parameters:
23		- # name (required) - Name
24		- # path (required) - Path
	26	+ # name (required) - The name of the group
	27	+ # path (required) - The path of the group
25	28	# Example Request:
26	29	# POST /groups
27	30	post do
28	31	authenticated_as_admin!
	32	+
	33	+ bad_request!(:name) unless params[:name].present?
	34	+ bad_request!(:path) unless params[:path].present?
	35	+
29	36	attrs = attributes_for_keys [:name, :path]
30	37	@group = Group.new(attrs)
31	38	@group.owner = current_user
...	...
...	...	@@ -88,6 +88,16 @@ describe Gitlab::API do
88	88	post api("/groups", admin), {:name => "Duplicate Test", :path => group2.path}
89	89	response.status.should == 404
90	90	end
	91	+
	92	+ it "should return 400 bad request error if name not given" do
	93	+ post api("/groups", admin), { :path => group2.path }
	94	+ response.status.should == 400
	95	+ end
	96	+
	97	+ it "should return 400 bad request error if path not given" do
	98	+ post api("/groups", admin), { :name => 'test' }
	99	+ response.status.should == 400
	100	+ end
91	101	end
92	102	end
93	103	end
...	...