Merge pull request #2835 from Asquera/fixes/api

Fix API return codes

app/models/merge_request.rb

@@ -91,7 +91,7 @@ class MergeRequest < ActiveRecord::Base
   def validate_branches
     if target_branch == source_branch
-      errors.add :base, "You can not use same branch for source and target branches"
+      errors.add :branch_conflict, "You can not use same branch for source and target branches"
     end
   end

app/models/project.rb

@@ -160,7 +160,7 @@ class Project < ActiveRecord::Base
   def check_limit
     unless creator.can_create_project?
-      errors[:base] << ("Your own projects limit is #{creator.projects_limit}! Please contact administrator to increase it")
+      errors[:limit_reached] << ("Your own projects limit is #{creator.projects_limit}! Please contact administrator to increase it")
     end
   rescue
     errors[:base] << ("Can't check your ability to create project")

config/routes.rb

@@ -8,6 +8,7 @@ Gitlab::Application.routes.draw do
   # API
   require 'api'
+  Gitlab::API.logger Rails.logger
   mount Gitlab::API => '/api'
   constraint = lambda { |request| request.env["warden"].authenticate? and request.env['warden'].user.admin? }

doc/api/README.md

 # GitLab API
-All API requests require authentication. You need to pass a `private_token` parameter by url or header. You can find or reset your private token in your profile.
+All API requests require authentication. You need to pass a `private_token` parameter by url or header. If passed as header, the header name must be "PRIVATE-TOKEN" (capital and with dash instead of underscore). You can find or reset your private token in your profile.
 If no, or an invalid, `private_token` is provided then an error message will be returned with status code 401:
@@ -18,8 +18,48 @@ Example of a valid API request:
 GET http://example.com/api/v3/projects?private_token=QVy1PB7sTxfy4pqfZM1U
 ```
+Example for a valid API request using curl and authentication via header:
+
+```
+curl --header "PRIVATE-TOKEN: QVy1PB7sTxfy4pqfZM1U" "http://example.com/api/v3/projects"
+```
+
+
 The API uses JSON to serialize data. You don't need to specify `.json` at the end of API URL.
+
+
+## Status codes
+
+The API is designed to return different status codes according to context and action. In this way
+if a request results in an error the caller is able to get insight into what went wrong, e.g.
+status code `400 Bad Request` is returned if a required attribute is missing from the request.
+The following list gives an overview of how the API functions generally behave.
+
+API request types:
+
+* `GET` requests access one or more resources and return the result as JSON
+* `POST` requests return `201 Created` if the resource is successfully created and return the newly created resource as JSON
+* `GET`, `PUT` and `DELETE` return `200 Ok` if the resource is accessed, modified or deleted successfully, the (modified) result is returned as JSON
+* `DELETE` requests are designed to be idempotent, meaning a request a resource still returns `200 Ok` even it was deleted before or is not available. The reasoning behind it is the user is not really interested if the resource existed before or not.
+
+
+The following list shows the possible return codes for API requests.
+
+Return values:
+
+* `200 Ok` - The `GET`, `PUT` or `DELETE` request was successful, the resource(s) itself is returned as JSON
+* `201 Created` - The `POST` request was successful and the resource is returned as JSON
+* `400 Bad Request` - A required attribute of the API request is missing, e.g. the title of an issue is not given
+* `401 Unauthorized` - The user is not authenticated, a valid user token is necessary, see above
+* `403 Forbidden` - The request is not allowed, e.g. the user is not allowed to delete a project
+* `404 Not Found` - A resource could not be accessed, e.g. an ID for a resource could not be found
+* `405 Method Not Allowed` - The request is not supported
+* `409 Conflict` - A conflicting resource already exists, e.g. creating a project with a name that already exists
+* `500 Server Error` - While handling the request something went wrong on the server side
+
+
+
 #### Pagination
 When listing resources you can pass the following parameters:

doc/api/groups.md

@@ -17,7 +17,8 @@ GET /groups
 ]
 ```
-## Details of group
+
+## Details of a group
 Get all details of a group.
@@ -29,19 +30,19 @@ Parameters:
 + `id` (required) - The ID of a group
+
 ## 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
 ## Transfer project to group

doc/api/issues.md

 ## List issues
-Get all issues created by authenticed user.
+Get all issues created by authenticed user. This function takes pagination parameters
+`page` and `per_page` to restrict the list of issues.
 ```
 GET /issues
@@ -68,9 +69,11 @@ GET /issues
 ]
 ```
+
 ## List project issues
-Get a list of project issues.
+Get a list of project issues. This function accepts pagination parameters `page` and `per_page`
+to return the list of project issues.
 ```
 GET /projects/:id/issues
@@ -80,9 +83,10 @@ Parameters:
 + `id` (required) - The ID of a project
+
 ## Single issue
-Get a project issue.
+Gets a single project issue.
 ```
 GET /projects/:id/issues/:issue_id
@@ -133,9 +137,10 @@ Parameters:
 }
 ```
+
 ## New issue
-Create a new project issue.
+Creates a new project issue.
 ```
 POST /projects/:id/issues
@@ -150,11 +155,10 @@ Parameters:
 + `milestone_id` (optional) - The ID of a milestone to assign issue
 + `labels` (optional) - Comma-separated label names for an issue
-Will return created issue with status `201 Created` on success, or `404 Not found` on fail.
 ## Edit issue
-Update an existing project issue.
+Updates an existing project issue. This function is also used to mark an issue as closed.
 ```
 PUT /projects/:id/issues/:issue_id
@@ -171,5 +175,19 @@ Parameters:
 + `labels` (optional) - Comma-separated label names for an issue
 + `closed` (optional) - The state of an issue (0 = false, 1 = true)
-Will return updated issue with status `200 OK` on success, or `404 Not found` on fail.
+
+## Delete existing issue (**Deprecated**)
+
+The function is deprecated and returns a `405 Method Not Allowed`
+error if called. An issue gets now closed and is done by calling `PUT /projects/:id/issues/:issue_id` with
+parameter `closed` set to 1.
+
+```
+DELETE /projects/:id/issues/:issue_id
+```
+
+Parameters:
+
++ `id` (required) - The project ID
++ `issue_id` (required) - The ID of the issue

doc/api/merge_requests.md

 ## List merge requests
-Get all MR for this project.
+Get all merge requests for this project. This function takes pagination parameters
+`page` and `per_page` to restrict the list of merge requests.
 ```
 GET /projects/:id/merge_requests
@@ -40,9 +41,10 @@ Parameters:
 ]
 ```
-## Show MR
-Show information about MR.
+## Get single MR
+
+Shows information about a single merge request.
 ```
 GET /projects/:id/merge_request/:merge_request_id
@@ -84,7 +86,7 @@ Parameters:
 ## Create MR
-Create MR.
+Creates a new merge request.
 ```
 POST /projects/:id/merge_requests
@@ -126,9 +128,10 @@ Parameters:
 }
 ```
+
 ## Update MR
-Update MR. You can change branches, title, or even close the MR.
+Updates an existing merge request. You can change branches, title, or even close the MR.
 ```
 PUT /projects/:id/merge_request/:merge_request_id
@@ -172,9 +175,11 @@ Parameters:
     }
 }
 ```
+
+
 ## Post comment to MR
-Post comment to MR
+Adds a comment to a merge request.
 ```
 POST /projects/:id/merge_request/:merge_request_id/comments
@@ -183,10 +188,9 @@ POST /projects/:id/merge_request/:merge_request_id/comments
 Parameters:
 + `id` (required) - The ID of a project
-+ `merge_request_id` (required) - ID of MR
++ `merge_request_id` (required) - ID of merge request
 + `note` (required) - Text of comment
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
 ```json
 {

doc/api/milestones.md

 ## List project milestones
-Get a list of project milestones.
+Returns a list of project milestones.
 ```
 GET /projects/:id/milestones
@@ -10,9 +10,10 @@ Parameters:
 + `id` (required) - The ID of a project
-## Single milestone
-Get a single project milestone.
+## Get single milestone
+
+Gets a single project milestone.
 ```
 GET /projects/:id/milestones/:milestone_id
@@ -23,9 +24,10 @@ Parameters:
 + `id` (required) - The ID of a project
 + `milestone_id` (required) - The ID of a project milestone
-## New milestone
-Create a new project milestone.
+## Create new milestone
+
+Creates a new project milestone.
 ```
 POST /projects/:id/milestones
@@ -38,9 +40,10 @@ Parameters:
 + `description` (optional) - The description of the milestone
 + `due_date` (optional) - The due date of the milestone
+
 ## Edit milestone
-Update an existing project milestone.
+Updates an existing project milestone.
 ```
 PUT /projects/:id/milestones/:milestone_id
@@ -54,3 +57,4 @@ Parameters:
 + `description` (optional) - The description of a milestone
 + `due_date` (optional) - The due date of the milestone
 + `closed` (optional) - The status of the milestone
+

doc/api/notes.md

-## List notes
+## Wall
 ### List project wall notes
@@ -30,22 +30,40 @@ Parameters:
 + `id` (required) - The ID of a project
-### List merge request notes
-Get a list of merge request notes.
+### Get single wall note
+
+Returns a single wall note.
 ```
-GET /projects/:id/merge_requests/:merge_request_id/notes
+GET /projects/:id/notes/:note_id
 ```
 Parameters:
 + `id` (required) - The ID of a project
-+ `merge_request_id` (required) - The ID of an merge request
-### List issue notes
-Get a list of issue notes.
++ `note_id` (required) - The ID of a wall note
+### Create new wall note
+
+Creates a new wall note.
+
+```
+POST /projects/:id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `body` (required) - The content of a note
+
+
+## Issues
+
+### List project issue notes
+
+Gets a list of all notes for a single issue.
 ```
 GET /projects/:id/issues/:issue_id/notes
@@ -56,54 +74,59 @@ Parameters:
 + `id` (required) - The ID of a project
 + `issue_id` (required) - The ID of an issue
-### List snippet notes
-Get a list of snippet notes.
+### Get single issue note
+
+Returns a single note for a specific project issue
 ```
-GET /projects/:id/snippets/:snippet_id/notes
+GET /projects/:id/issues/:issue_id/notes/:note_id
 ```
 Parameters:
 + `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of a snippet
-## Single note
-### Single wall note
-Get a wall note.
++ `issue_id` (required) - The ID of a project issue
++ `note_id` (required) - The ID of an issue note
+### Create new issue note
+Creates a new note to a single project issue.
 ```
-GET /projects/:id/notes/:note_id
+POST /projects/:id/issues/:issue_id/notes
 ```
 Parameters:
 + `id` (required) - The ID of a project
-+ `note_id` (required) - The ID of a wall note
-### Single issue note
-Get an issue note.
++ `issue_id` (required) - The ID of an issue
++ `body` (required) - The content of a note
+## Snippets
+
+### List all snippet notes
+
+Gets a list of all notes for a single snippet. Snippet notes are comments users can post to a snippet.
 ```
-GET /projects/:id/issues/:issue_id/:notes/:note_id
+GET /projects/:id/snippets/:snippet_id/notes
 ```
 Parameters:
 + `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of a project issue
-+ `note_id` (required) - The ID of an issue note
-### Single snippet note
-Get a snippet note.
++ `snippet_id` (required) - The ID of a project snippet
+
+### Get single snippet note
+Returns a single note for a given snippet.
 ```
-GET /projects/:id/issues/:snippet_id/:notes/:note_id
+GET /projects/:id/snippets/:snippet_id/notes/:note_id
 ```
 Parameters:
@@ -112,52 +135,64 @@ Parameters:
 + `snippet_id` (required) - The ID of a project snippet
 + `note_id` (required) - The ID of an snippet note
-## New note
-### New wall note
-Create a new wall note.
+### Create new snippet note
+Creates a new note for a single snippet. Snippet notes are comments users can post to a snippet.
 ```
-POST /projects/:id/notes
+POST /projects/:id/snippets/:snippet_id/notes
 ```
 Parameters:
 + `id` (required) - The ID of a project
++ `snippet_id` (required) - The ID of an snippet
 + `body` (required) - The content of a note
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
-### New issue note
-Create a new issue note.
+## Merge Requests
+### List all merge request notes
+Gets a list of all notes for a single merge request.
 ```
-POST /projects/:id/issues/:issue_id/notes
+GET /projects/:id/merge_requests/:merge_request_id/notes
 ```
 Parameters:
 + `id` (required) - The ID of a project
-+ `issue_id` (required) - The ID of an issue
-+ `body` (required) - The content of a note
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
-### New snippet note
-Create a new snippet note.
++ `merge_request_id` (required) - The ID of a project merge request
+### Get single merge request note
+Returns a single note for a given merge request.
 ```
-POST /projects/:id/snippets/:snippet_id/notes
+GET /projects/:id/merge_requests/:merge_request_id/notes/:note_id
 ```
 Parameters:
 + `id` (required) - The ID of a project
-+ `snippet_id` (required) - The ID of an snippet
++ `merge_request_id` (required) - The ID of a project merge request
++ `note_id` (required) - The ID of a merge request note
+
+
+### Create new merge request note
+
+Creates a new note for a single merge request.
+
+```
+POST /projects/:id/merge_requests/:merge_request_id/notes
+```
+
+Parameters:
+
++ `id` (required) - The ID of a project
++ `merge_request_id` (required) - The ID of a merge request
 + `body` (required) - The content of a note
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.

doc/api/projects.md

-## List projects
+## Projects
+
+### List projects
 Get a list of projects owned by the authenticated user.
@@ -55,9 +57,11 @@ GET /projects
 ]
 ```
-## Single project
-Get a specific project, identified by project ID, which is owned by the authentication user.
+### Get single project
+
+Get a specific project, identified by project ID or NAME, which is owned by the authentication user.
+Currently namespaced projects cannot retrieved by name.
 ```
 GET /projects/:id
@@ -65,7 +69,7 @@ GET /projects/:id
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 ```json
 {
@@ -92,9 +96,10 @@ Parameters:
 }
 ```
-## Create project
-Create new project owned by user
+### Create project
+
+Creates new project owned by user.
 ```
 POST /projects
@@ -110,12 +115,21 @@ Parameters:
 + `merge_requests_enabled` (optional) - enabled by default
 + `wiki_enabled` (optional) - enabled by default
-Will return created project with status `201 Created` on success, or `404 Not
-found` on fail.
-## Create project for user
-Create new project owned by user. Available only for admin
+**Project access levels**
+The project access levels are defined in the `user_project.rb` class. Currently, these levels are recoginized:
+
+```
+  GUEST     = 10
+  REPORTER  = 20
+  DEVELOPER = 30
+  MASTER    = 40
+```
+
+### Create project for user
+
+Creates a new project owned by user. Available only for admins.
 ```
 POST /projects/user/:user_id
@@ -132,10 +146,11 @@ Parameters:
 + `merge_requests_enabled` (optional) - enabled by default
 + `wiki_enabled` (optional) - enabled by default
-Will return created project with status `201 Created` on success, or `404 Not
-found` on fail.
-## List project team members
+
+## Team members
+
+### List project team members
 Get a list of project team members.
@@ -145,12 +160,13 @@ GET /projects/:id/members
 Parameters:
-+ `id` (required) - The ID of a project
-+ `query`         - Query string
-## Get project team member
-Get a project team member.
++ `id` (required) - The ID or NAME of a project
++ `query` (optional) - Query string to search for members
+
+### Get project team member
+Gets a project team member.
 ```
 GET /projects/:id/members/:user_id
@@ -158,12 +174,11 @@ GET /projects/:id/members/:user_id
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a user
 ```json
 {
-
   "id": 1,
   "username": "john_smith",
   "email": "john@example.com",
@@ -174,9 +189,12 @@ Parameters:
 }
 ```
-## Add project team member
-Add a user to a project team.
+### Add project team member
+
+Adds a user to a project team. This is an idempotent method and can be called multiple times
+with the same parameters. Adding team membership to a user that is already a member does not
+affect the existing membership.
 ```
 POST /projects/:id/members
@@ -184,15 +202,14 @@ POST /projects/:id/members
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a user to add
 + `access_level` (required) - Project access level
-Will return status `201 Created` on success, or `404 Not found` on fail.
-## Edit project team member
-Update project team member to specified access level.
+### Edit project team member
+Updates project team member to a specified access level.
 ```
 PUT /projects/:id/members/:user_id
@@ -200,13 +217,12 @@ PUT /projects/:id/members/:user_id
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a team member
 + `access_level` (required) - Project access level
-Will return status `200 OK` on success, or `404 Not found` on fail.
-## Remove project team member
+### Remove project team member
 Removes user from project team.
@@ -216,14 +232,20 @@ DELETE /projects/:id/members/:user_id
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `user_id` (required) - The ID of a team member
-Status code `200` will be returned on success.
-## List project hooks
-Get list for project hooks
+This method is idempotent and can be called multiple times with the same parameters.
+Revoking team membership for a user who is not currently a team member is considered success.
+Please note that the returned JSON currently differs slightly. Thus you should not
+rely on the returned JSON structure.
+
+## Hooks
+### List project hooks
+
+Get list of project hooks.
 ```
 GET /projects/:id/hooks
@@ -231,13 +253,12 @@ GET /projects/:id/hooks
 Parameters:
-+ `id` (required) - The ID of a project
-Will return hooks with status `200 OK` on success, or `404 Not found` on fail.
-## Get project hook
-Get hook for project
++ `id` (required) - The ID or NAME of a project
+### Get project hook
+Get a specific hook for project.
 ```
 GET /projects/:id/hooks/:hook_id
@@ -245,14 +266,21 @@ GET /projects/:id/hooks/:hook_id
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `hook_id` (required) - The ID of a project hook
-Will return hook with status `200 OK` on success, or `404 Not found` on fail.
-## Add project hook
-Add hook to project
+```json
+{
+  "id": 1,
+  "url": "http://example.com/hook",
+  "created_at": "2012-10-12T17:04:47Z"
+}
+```
+### Add project hook
+
+Adds a hook to project.
 ```
 POST /projects/:id/hooks
@@ -260,14 +288,13 @@ POST /projects/:id/hooks
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `url` (required) - The hook URL
-Will return status `201 Created` on success, or `404 Not found` on fail.
-## Edit project hook
-Edit hook for project
+### Edit project hook
+Edits a hook for project.
 ```
 PUT /projects/:id/hooks/:hook_id
@@ -275,30 +302,125 @@ PUT /projects/:id/hooks/:hook_id
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `hook_id` (required) - The ID of a project hook
 + `url` (required) - The hook URL
-Will return status `201 Created` on success, or `404 Not found` on fail.
-
-## Delete project hook
-Delete hook from project
+### Delete project hook
+Removes a hook from project. This is an idempotent method and can be called multiple times.
+Either the hook is available or not.
 ```
-DELETE /projects/:id/hooks/:hook_id
+DELETE /projects/:id/hooks/
 ```
 Parameters:
-+ `id` (required) - The ID of a project
++ `id` (required) - The ID or NAME of a project
 + `hook_id` (required) - The ID of hook to delete
-Will return status `200 OK` on success, or `404 Not found` on fail.
-## List deploy keys
+Note the JSON response differs if the hook is available or not. If the project hook
+is available before it is returned in the JSON response or an empty response is returned.
+## Branches
+
+### List branches
+
+Lists all branches of a project.
+
+```
+GET /projects/:id/repository/branches
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
+
+
+### List single branch
+
+Lists a specific branch of a project.
+
+```
+GET /projects/:id/repository/branches/:branch
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project.
++ `branch` (required) - The name of the branch.
+
+
+### Protect single branch
+
+Protects a single branch of a project.
+
+```
+PUT /projects/:id/repository/branches/:branch/protect
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project.
++ `branch` (required) - The name of the branch.
+
+
+### Unprotect single branch
+
+Unprotects a single branch of a project.
+
+```
+PUT /projects/:id/repository/branches/:branch/unprotect
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project.
++ `branch` (required) - The name of the branch.
+
+
+### List tags
+
+Lists all tags of a project.
+
+```
+GET /projects/:id/repository/tags
+```
+
+Parameters:
+
++ `id` (required) - The ID of the project
+
+
+### List commits
+
+Lists all commits with pagination. If the optional `ref_name` name is not given the commits of
+the default branch (usually master) are returned.
+
+```
+GET /projects/:id/repository/commits
+```
+
+Parameters:
+
++ `id` (required) - The Id of the project
++ `ref_name` (optional) - The name of a repository branch or tag
++ `page` (optional) - The page of commits to return (`0` default)
++ `per_page` (optional) - The number of commits per page (`20` default)
+
+Returns values:
+
++ `200 Ok` on success and a list with commits
++ `404 Not Found` if project with id or the branch with `ref_name` not found
+
+
+
+## Deploy Keys
+
+### List deploy keys
 Get a list of a project's deploy keys.
@@ -306,6 +428,10 @@ Get a list of a project's deploy keys.
 GET /projects/:id/keys
 ```
+Parameters:
+
++ `id` (required) - The ID of the project
+
 ```json
 [
   {
@@ -325,7 +451,8 @@ GET /projects/:id/keys
 ]
 ```
-## Single deploy key
+
+### Single deploy key
 Get a single key.
@@ -335,7 +462,8 @@ GET /projects/:id/keys/:key_id
 Parameters:
-+ `id` (required) - The ID of an deploy key
++ `id` (required) - The ID of the project
++ `key_id` (required) - The ID of the deploy key
 ```json
 {
@@ -346,9 +474,11 @@ Parameters:
       soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
 }
 ```
-## Add deploy key
-Create new deploy key for a project
+
+### Add deploy key
+
+Creates a new deploy key for a project.
 ```
 POST /projects/:id/keys
@@ -356,13 +486,12 @@ POST /projects/:id/keys
 Parameters:
-+ `title` (required) - new deploy key's title
-+ `key` (required) - new deploy key
-Will return created key with status `201 Created` on success, or `404 Not
-found` on fail.
-## Delete deploy key
++ `id` (required) - The ID of the project
++ `title` (required) - New deploy key's title
++ `key` (required) - New deploy key
+### Delete deploy key
 Delete a deploy key from a project
@@ -372,6 +501,6 @@ DELETE /projects/:id/keys/:key_id
 Parameters:
-+ `id` (required) - Deploy key ID
-Will return `200 OK` on success, or `404 Not Found` on fail.
++ `id` (required) - The ID of the project
++ `key_id` (required) - The ID of the deploy key

doc/api/repositories.md

-## Project repository branches
+## List repository branches
 Get a list of repository branches from a project, sorted by name alphabetically.
@@ -39,7 +39,8 @@ Parameters:
 ]
 ```
-## Project repository branch
+
+## Get single repository branch
 Get a single project repository branch.
@@ -79,12 +80,11 @@ Parameters:
 }
 ```
-Will return status code `200` on success or `404 Not found` if the branch is not available.
-
-## Protect a project repository branch
-Protect a single project repository branch.
+## Protect repository branch
+Protects a single project repository branch. This is an idempotent function, protecting an already
+protected repository branch still returns a `200 Ok` status code.
 ```
 PUT /projects/:id/repository/branches/:branch/protect
@@ -122,9 +122,11 @@ Parameters:
 }
 ```
-## Unprotect a project repository branch
-Unprotect a single project repository branch.
+## Unprotect repository branch
+
+Unprotects a single project repository branch. This is an idempotent function, unprotecting an already
+unprotected repository branch still returns a `200 Ok` status code.
 ```
 PUT /projects/:id/repository/branches/:branch/unprotect
@@ -162,7 +164,8 @@ Parameters:
 }
 ```
-## Project repository tags
+
+## List project repository tags
 Get a list of repository tags from a project, sorted by name in reverse alphabetical order.
@@ -201,7 +204,8 @@ Parameters:
 ]
 ```
-## Project repository commits
+
+## List repository commits
 Get a list of repository commits in a project.
@@ -212,7 +216,7 @@ GET /projects/:id/repository/commits
 Parameters:
 + `id` (required) - The ID of a project
-+ `ref_name` (optional) - The name of a repository branch or tag
++ `ref_name` (optional) - The name of a repository branch or tag or if not given the default branch
 ```json
 [
@@ -235,6 +239,7 @@ Parameters:
 ]
 ```
+
 ## Raw blob content
 Get the raw file contents for a file.
@@ -248,5 +253,3 @@ Parameters:
 + `id` (required) - The ID of a project
 + `sha` (required) - The commit or branch name
 + `filepath` (required) - The path the file
-
-Will return the raw file contents.

doc/api/snippets.md

@@ -10,9 +10,10 @@ Parameters:
 + `id` (required) - The ID of a project
+
 ## Single snippet
-Get a project snippet.
+Get a single project snippet.
 ```
 GET /projects/:id/snippets/:snippet_id
@@ -42,22 +43,10 @@ Parameters:
 }
 ```
-## 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
-## New snippet
-Create a new project snippet.
+## Create new snippet
+Creates a new project snippet. The user must have permission to create new snippets.
 ```
 POST /projects/:id/snippets
@@ -71,11 +60,10 @@ 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.
-## Edit snippet
-Update an existing project snippet.
+## Update snippet
+Updates an existing project snippet. The user must have permission to change an existing snippet.
 ```
 PUT /projects/:id/snippets/:snippet_id
@@ -90,11 +78,11 @@ 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.
 ## 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 +93,16 @@ 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.
+## Snippet content
+
+Returns the raw project snippet as plain text.
+
+```
+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

doc/api/users.md

@@ -43,6 +43,7 @@ GET /users
 ]
 ```
+
 ## Single user
 Get a single user.
@@ -74,37 +75,40 @@ Parameters:
 }
 ```
+
 ## User creation
-Create user. Available only for admin
+
+Creates a new user. Note only administrators can create new users.
 ```
 POST /users
 ```
 Parameters:
-+ `email` (required)                  - Email
-+ `password` (required)               - Password
-+ `username` (required)               - Username
-+ `name` (required)                   - Name
-+ `skype`                             - Skype ID
-+ `linkedin`                          - Linkedin
-+ `twitter`                           - Twitter account
-+ `projects_limit`                    - Number of projects user can create
-+ `extern_uid`                        - External UID
-+ `provider`                          - External provider name
-+ `bio`                               - User's bio
-Will return created user with status `201 Created` on success, or `404 Not
-found` on fail.
++ `email` (required)          - Email
++ `password` (required)       - Password
++ `username` (required)       - Username
++ `name` (required)           - Name
++ `skype` (optional)          - Skype ID
++ `linkedin` (optional)       - Linkedin
++ `twitter` (optional)        - Twitter account
++ `projects_limit` (optional) - Number of projects user can create
++ `extern_uid` (optional)     - External UID
++ `provider` (optional)       - External provider name
++ `bio` (optional)            - User's bio
+
 ## User modification
-Modify user. Available only for admin
+
+Modifies an existing user. Only administrators can change attributes of a user.
 ```
 PUT /users/:id
 ```
 Parameters:
+
 + `email`                             - Email
 + `username`                          - Username
 + `name`                              - Name
@@ -117,23 +121,28 @@ Parameters:
 + `provider`                          - External provider name
 + `bio`                               - User's bio
-Will return created user with status `200 OK` on success, or `404 Not
-found` on fail.
+Note, at the moment this method does only return a 404 error, even in cases where a 409 (Conflict) would
+be more appropriate, e.g. when renaming the email address to some exsisting one.
 ## User deletion
-Delete user. Available only for admin
+
+Deletes a user. Available only for administrators. This is an idempotent function, calling this function
+for a non-existent user id still returns a status code `200 Ok`. The JSON response differs if the user
+was actually deleted or not. In the former the user is returned and in the latter not.
 ```
 DELETE /users/:id
 ```
-Will return deleted user with status `200 OK` on success, or `404 Not
-found` on fail.
+Parameters:
+
++ `id` (required) - The ID of the user
+
 ## Current user
-Get currently authenticated user.
+Gets currently authenticated user.
 ```
 GET /user
@@ -156,6 +165,7 @@ GET /user
 }
 ```
+
 ## List SSH keys
 Get a list of currently authenticated user's SSH keys.
@@ -183,6 +193,11 @@ GET /user/keys
 ]
 ```
+Parameters:
+
++ **none**
+
+
 ## Single SSH key
 Get a single key.
@@ -204,9 +219,11 @@ Parameters:
       soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0="
 }
 ```
+
+
 ## Add SSH key
-Create new key owned by currently authenticated user
+Creates a new key owned by the currently authenticated user.
 ```
 POST /user/keys
@@ -217,8 +234,6 @@ Parameters:
 + `title` (required) - new SSH Key's title
 + `key` (required) - new SSH key
-Will return created key with status `201 Created` on success, or `404 Not
-found` on fail.
 ## Add SSH key for user
@@ -239,7 +254,8 @@ found` on fail.
 ## Delete SSH key
-Delete key owned by currently authenticated user
+Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already
+deleted or not available results in `200 Ok`.
 ```
 DELETE /user/keys/:id
@@ -249,4 +265,3 @@ Parameters:
 + `id` (required) - SSH key ID
-Will return `200 OK` on success, or `404 Not Found` on fail.

lib/api.rb

@@ -8,6 +8,19 @@ module Gitlab
       rack_response({'message' => '404 Not found'}.to_json, 404)
     end
+    rescue_from :all do |exception|
+      # lifted from https://github.com/rails/rails/blob/master/actionpack/lib/action_dispatch/middleware/debug_exceptions.rb#L60
+      # why is this not wrapped in something reusable?
+      trace = exception.backtrace
+
+      message = "\n#{exception.class} (#{exception.message}):\n"
+      message << exception.annoted_source_code.to_s if exception.respond_to?(:annoted_source_code)
+      message << "  " << trace.join("\n  ")
+
+      API.logger.add Logger::FATAL, message 
+      rack_response({'message' => '500 Internal Server Error'}, 500)
+    end
+
     format :json
     helpers APIHelpers
     

lib/api/groups.rb

@@ -20,12 +20,14 @@ 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!
+        required_attributes! [:name, :path]
+
         attrs = attributes_for_keys [:name, :path]
         @group = Group.new(attrs)
         @group.owner = current_user

lib/api/helpers.rb

@@ -41,6 +41,17 @@ module Gitlab
       abilities.allowed?(object, action, subject)
     end
+    # Checks the occurrences of required attributes, each attribute must be present in the params hash
+    # or a Bad Request error is invoked.
+    #
+    # Parameters:
+    #   keys (required) - A hash consisting of keys that must be present
+    def required_attributes!(keys)
+      keys.each do |key|
+        bad_request!(key) unless params[key].present?
+      end
+    end
+
     def attributes_for_keys(keys)
       attrs = {}
       keys.each do |key|
@@ -55,6 +66,12 @@ module Gitlab
       render_api_error!('403 Forbidden', 403)
     end
+    def bad_request!(attribute)
+      message = ["400 (Bad request)"]
+      message << "\"" + attribute.to_s + "\" not given"
+      render_api_error!(message.join(' '), 400)
+    end
+
     def not_found!(resource = nil)
       message = ["404"]
       message << resource if resource

lib/api/issues.rb

@@ -48,6 +48,7 @@ module Gitlab
       # Example Request:
       #   POST /projects/:id/issues
       post ":id/issues" do
+        required_attributes! [:title]
         attrs = attributes_for_keys [:title, :description, :assignee_id, :milestone_id]
         attrs[:label_list] = params[:labels] if params[:labels].present?
         @issue = user_project.issues.new attrs

lib/api/merge_requests.rb

@@ -4,6 +4,16 @@ module Gitlab
     before { authenticate! }
     resource :projects do
+      helpers do
+        def handle_merge_request_errors!(errors)
+          if errors[:project_access].any?
+            error!(errors[:project_access], 422)
+          elsif errors[:branch_conflict].any?
+            error!(errors[:branch_conflict], 422)
+          end
+          not_found!
+        end
+      end
       # List merge requests
       #
@@ -51,6 +61,7 @@ module Gitlab
       #
       post ":id/merge_requests" do
         authorize! :write_merge_request, user_project
+        required_attributes! [:source_branch, :target_branch, :title]
         attrs = attributes_for_keys [:source_branch, :target_branch, :assignee_id, :title]
         merge_request = user_project.merge_requests.new(attrs)
@@ -60,7 +71,7 @@ module Gitlab
           merge_request.reload_code
           present merge_request, with: Entities::MergeRequest
         else
-          not_found!
+          handle_merge_request_errors! merge_request.errors
         end
       end
@@ -88,7 +99,7 @@ module Gitlab
           merge_request.mark_as_unchecked
           present merge_request, with: Entities::MergeRequest
         else
-          not_found!
+          handle_merge_request_errors! merge_request.errors
         end
       end
@@ -102,6 +113,8 @@ module Gitlab
       #   POST /projects/:id/merge_request/:merge_request_id/comments
       #
       post ":id/merge_request/:merge_request_id/comments" do
+        required_attributes! [:note]
+
         merge_request = user_project.merge_requests.find(params[:merge_request_id])
         note = merge_request.notes.new(note: params[:note], project_id: user_project.id)
         note.author = current_user

lib/api/milestones.rb

@@ -41,6 +41,7 @@ module Gitlab
       #   POST /projects/:id/milestones
       post ":id/milestones" do
         authorize! :admin_milestone, user_project
+        required_attributes! [:title]
         attrs = attributes_for_keys [:title, :description, :due_date]
         @milestone = user_project.milestones.new attrs

lib/api/notes.rb

@@ -37,12 +37,16 @@ module Gitlab
       # Example Request:
       #   POST /projects/:id/notes
       post ":id/notes" do
+        required_attributes! [:body]
+
         @note = user_project.notes.new(note: params[:body])
         @note.author = current_user
         if @note.save
           present @note, with: Entities::Note
         else
+          # :note is exposed as :body, but :note is set on error
+          bad_request!(:note) if @note.errors[:note].any?
           not_found!
         end
       end
@@ -89,6 +93,8 @@ module Gitlab
         #   POST /projects/:id/issues/:noteable_id/notes
         #   POST /projects/:id/snippets/:noteable_id/notes
         post ":id/#{noteables_str}/:#{noteable_id_str}/notes" do
+          required_attributes! [:body]
+
           @noteable = user_project.send(:"#{noteables_str}").find(params[:"#{noteable_id_str}"])
           @note = @noteable.notes.new(note: params[:body])
           @note.author = current_user