diff options
| -rw-r--r-- | doc/api/projects.md | 151 |
1 files changed, 117 insertions, 34 deletions
diff --git a/doc/api/projects.md b/doc/api/projects.md index 03731427703..a36890a41e3 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1,4 +1,6 @@ -## 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. |