API: fixes return codes, documentation updated with status codes, tests added

The users API updated with return codes, e.g. if required parameters are missing
a `400 Bad Request` error is returned instead of `404`. Fixes return codes of functions,
e.g. deletion of a ssh key is an idempotent function now.
The API documentation is updated to reflect the current status of the API. Descriptions
are more detailed and complete, infos to return values are added to all functions.

lib/api/users.rb

@@ -41,6 +41,12 @@ module Gitlab
       #   POST /users
       post do
         authenticated_as_admin!
+
+        bad_request!(:email)    if !params.has_key? :email
+        bad_request!(:password) if !params.has_key? :password
+        bad_request!(:name)     if !params.has_key? :name
+        bad_request!(:username) if !params.has_key? :username
+
         attrs = attributes_for_keys [:email, :name, :password, :skype, :linkedin, :twitter, :projects_limit, :username, :extern_uid, :provider, :bio]
         user = User.new attrs, as: :admin
         if user.save
@@ -67,10 +73,12 @@ module Gitlab
       #   PUT /users/:id
       put ":id" do
         authenticated_as_admin!
-        attrs = attributes_for_keys [:email, :name, :password, :skype, :linkedin, :twitter, :projects_limit, :username, :extern_uid, :provider, :bio]
-        user = User.find_by_id(params[:id])
 
-        if user && user.update_attributes(attrs)
+        attrs = attributes_for_keys [:email, :name, :password, :skype, :linkedin, :twitter, :projects_limit, :username, :extern_uid, :provider, :bio]
+        user = User.find(params[:id])
+        not_found!("User not found") unless user
+
+        if user.update_attributes(attrs)
           present user, with: Entities::User
         else
           not_found!
@@ -127,6 +135,9 @@ module Gitlab
       # Example Request:
       #   POST /user/keys
       post "keys" do
+        bad_request!(:title) unless params[:title].present?
+        bad_request!(:key) unless params[:key].present?
+
         attrs = attributes_for_keys [:title, :key]
         key = current_user.keys.new attrs
         if key.save
@@ -136,15 +147,18 @@ module Gitlab
         end
       end
 
-      # Delete existed ssh key of currently authenticated user
+      # Delete existing ssh key of currently authenticated user
       #
       # Parameters:
       #   id (required) - SSH Key ID
       # Example Request:
       #   DELETE /user/keys/:id
       delete "keys/:id" do
-        key = current_user.keys.find params[:id]
-        key.delete
+        begin
+          key = current_user.keys.find params[:id]
+          key.delete
+        rescue
+        end
       end
     end
   end