API projects documentation grouped into sections & updated with status codes

doc/api/projects.md

-## List projects
+## Projects
+
+### List projects
 
 Get a list of projects owned by the authenticated user.
 
@@ -55,7 +57,8 @@ GET /projects
 ]
 ```
 
-## Single project
+
+### Get single project
 
 Get a specific project, identified by project ID, which is owned by the authentication user.
 
@@ -92,9 +95,15 @@ Parameters:
 }
 ```
 
-## Create project
+Return Values:
+
++ `200 Ok` if the project with given ID is found and the JSON response
++ `404 Not Found` if no project with ID found
+
+
+### Create project
 
-Create new project owned by user
+Creates new project owned by user.
 
 ```
 POST /projects
@@ -110,10 +119,15 @@ 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.
+Return values:
 
-## List project team members
++ `201 Created` on success with the project data (see example at `GET /projects/:id`)
++ `400 Bad Request` if the required attribute name is not given
++ `403 Forbidden` if the user is not allowed to create a project, e.g. reached the project limit already
++ `404 Not Found` if something else fails
+
+
+### List project members
 
 Get a list of project team members.
 
@@ -126,7 +140,15 @@ Parameters:
 + `id` (required) - The ID of a project
 + `query`         - Query string
 
-## Get project team member
+Return Values:
+
++ `200 Ok` on success and a list of found team members
++ `404 Not Found` if project with ID not found
+
+
+## Team members
+
+### Get project team member
 
 Get a project team member.
 
@@ -141,7 +163,6 @@ Parameters:
 
 ```json
 {
-
   "id": 1,
   "username": "john_smith",
   "email": "john@example.com",
@@ -152,9 +173,17 @@ Parameters:
 }
 ```
 
-## Add project team member
+Return Values:
+
++ `200 Ok` on success and the team member, see example
++ `404 Not Found` if either the project or the team member could not be found
+
+
+### Add project team member
 
-Add a user to a project team.
+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 membership.
 
 ```
 POST /projects/:id/members
@@ -166,9 +195,15 @@ Parameters:
 + `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.
+Return Values:
 
-## Edit project team member
++ `200 Ok` on success and the added user, even if the user is already team member
++ `400 Bad Request` if the required attribute access_level is not given
++ `404 Not Found` if a resource can not be found, e.g. project with ID not available
++ `422 Unprocessable Entity` if an unknown access_level is given
+
+
+### Edit project team member
 
 Update project team member to specified access level.
 
@@ -182,9 +217,15 @@ Parameters:
 + `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.
+Return Values:
+
++ `200 Ok` on succes and the modified team member
++ `400 Bad Request` if the required attribute access_level is not given
++ `404 Not Found` if a resource can not be found, e.g. project with ID not available
++ `422 Unprocessable Entity` if an unknown access_level is given
 
-## Remove project team member
+
+### Remove project team member
 
 Removes user from project team.
 
@@ -197,14 +238,22 @@ Parameters:
 + `id` (required) - The ID of a project
 + `user_id` (required) - The ID of a team member
 
-Status code `200 OK` will be returned on success. This method is idempotent and call 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
+Return Values:
+
++ `200 Ok` on success
++ `404 Not Found` if either project or user can not be found
+
+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.
 
-## List project hooks
 
-Get list for project hooks
+## Hooks
+
+### List project hooks
+
+Get list of project hooks.
 
 ```
 GET /projects/:id/hooks
@@ -214,26 +263,42 @@ Parameters:
 
 + `id` (required) - The ID of a project
 
-Will return hooks with status `200 OK` on success, or `404 Not found` on fail.
+Return values:
+
++ `200 Ok` on success with a list of hooks
++ `404 Not Found` if project can not be found
+
 
-## Get project hook
+### Get project hook
 
-Get hook for project
+Get a specific hook for project.
 
 ```
 GET /projects/:id/hooks/:hook_id
 ```
 
-Parameters:§
+Parameters:
 
 + `id` (required) - The ID 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.
+```json
+{
+  "id": 1,
+  "url": "http://example.com/hook",
+  "created_at": "2012-10-12T17:04:47Z"
+}
+```
+
+Return values:
+
++ `200 Ok` on sucess and the hook with the given ID
++ `404 Not Found` if the hook can not be found
 
-## Add project hook
 
-Add hook to project
+### Add project hook
+
+Adds a hook to project.
 
 ```
 POST /projects/:id/hooks
@@ -244,11 +309,17 @@ Parameters:
 + `id` (required) - The ID of a project
 + `url` (required) - The hook URL
 
-Will return status `201 Created` on success, or `404 Not found` on fail.
+Return values:
+
++ `201 Created` on success and the newly created hook
++ `400 Bad Request` if url is not given
++ `404 Not Found` if project with ID not found
++ `422 Unprocessable Entity` if the url is invalid (must begin with `http` or `https`)
 
-## Edit project hook
 
-Edit hook for project
+### Edit project hook
+
+Edits a hook for project.
 
 ```
 PUT /projects/:id/hooks/:hook_id
@@ -260,12 +331,18 @@ Parameters:
 + `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.
+Return values:
+
++ `200 Ok` on success and the modified hook (see JSON response above)
++ `400 Bad Request` if the url attribute is not given
++ `404 Not Found` if project or hook can not be found
++ `422 Unprocessable Entity` if the url is invalid (must begin with `http` or `https`)
 
 
-## Delete project hook
+### Delete project hook
 
-Delete hook from project
+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
@@ -276,4 +353,10 @@ Parameters:
 + `id` (required) - The ID 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.
+Return values:
+
++ `200 Ok` on succes
++ `404 Not Found` if the project can not be found
+
+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.