diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api/README.md | 13 | ||||
| -rw-r--r-- | doc/api/groups.md | 11 | ||||
| -rw-r--r-- | doc/api/projects.md | 124 | ||||
| -rw-r--r-- | doc/api/snippets.md | 8 | ||||
| -rw-r--r-- | doc/api/system_hooks.md | 47 | ||||
| -rw-r--r-- | doc/api/users.md | 17 | ||||
| -rw-r--r-- | doc/install/installation.md | 2 |
7 files changed, 161 insertions, 61 deletions
diff --git a/doc/api/README.md b/doc/api/README.md index 2699434d00b..f6c4e41b6cd 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -31,13 +31,10 @@ The API uses JSON to serialize data. You don't need to specify `.json` at the en ## Status codes -API requests return different status codes according to - -The API is designed to provide status codes according to the context and how the request -is handled. For example if a `GET` request is successful a status code `200 Ok` -is returned. The API is designed to be RESTful. - -The following list gives an overview of how the API functions are designed. +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: @@ -58,7 +55,7 @@ Return values: * `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, a project with same name already exists +* `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 diff --git a/doc/api/groups.md b/doc/api/groups.md index 25b9741f68a..e9702ea2cd1 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -44,3 +44,14 @@ Parameters: + `name` (required) - The name of the group + `path` (required) - The path of the group +## Transfer project to group + +Transfer a project to the Group namespace. Available only for admin + +``` +POST /groups/:id/projects/:project_id +``` + +Parameters: ++ `id` (required) - The ID of a group ++ `project_id (required) - The ID of a project diff --git a/doc/api/projects.md b/doc/api/projects.md index 326a62b0154..d6a9a8854ca 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -115,11 +115,9 @@ Parameters: + `merge_requests_enabled` (optional) - enabled by default + `wiki_enabled` (optional) - enabled by default +**Project access levels** -## Project access levels - -The project access levels are defined in the `user_project` class. Currently, 4 -levels are recoginized: +The project access levels are defined in the `user_project.rb` class. Currently, these levels are recoginized: ``` GUEST = 10 @@ -129,7 +127,30 @@ levels are recoginized: ``` -## List project team members +### Create project for user + +Creates a new project owned by user. Available only for admins. + +``` +POST /projects/user/:user_id +``` + +Parameters: + ++ `user_id` (required) - user_id of owner ++ `name` (required) - new project name ++ `description` (optional) - short project description ++ `default_branch` (optional) - 'master' by default ++ `issues_enabled` (optional) - enabled by default ++ `wall_enabled` (optional) - enabled by default ++ `merge_requests_enabled` (optional) - enabled by default ++ `wiki_enabled` (optional) - enabled by default + + + +## Team members + +### List project team members Get a list of project team members. @@ -140,14 +161,12 @@ GET /projects/:id/members Parameters: + `id` (required) - The ID or NAME of a project -+ `query` - Query string - ++ `query` (optional) - Query string to search for members -## Team members ### Get project team member -Get a project team member. +Gets a project team member. ``` GET /projects/:id/members/:user_id @@ -175,7 +194,7 @@ Parameters: 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. +affect the existing membership. ``` POST /projects/:id/members @@ -190,7 +209,7 @@ Parameters: ### Edit project team member -Update project team member to specified access level. +Updates project team member to a specified access level. ``` PUT /projects/:id/members/:user_id @@ -398,81 +417,90 @@ Returns values: + `404 Not Found` if project with id or the branch with `ref_name` not found -## Snippets -### List snippets +## Deploy Keys + +### List deploy keys -Lists the snippets of a project. +Get a list of a project's deploy keys. ``` -GET /projects/:id/snippets +GET /projects/:id/keys ``` Parameters: + `id` (required) - The ID of the project - -### List single snippet - -Lists a single snippet of a project - -``` -GET /projects/:id/snippets/:snippet_id +```json +[ + { + "id": 1, + "title" : "Public key" + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + }, + { + "id": 3, + "title" : "Another Public key" + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=" + } +] ``` -Parameters: - -+ `id` (required) - The ID of the project -+ `snippet_id` (required) - The ID of the snippet +### Single deploy key -### Create snippet - -Creates a new project snippet. +Get a single key. ``` -POST /projects/:id/snippets +GET /projects/:id/keys/:key_id ``` Parameters: + `id` (required) - The ID of the project -+ `title` (required) - The title of the new snippet -+ `file_name` (required) - The file name of the snippet -+ `code` (required) - The content of the snippet -+ `lifetime` (optional) - The expiration date of a snippet ++ `key_id` (required) - The ID of the deploy key +```json +{ + "id": 1, + "title" : "Public key" + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4 + 596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4 + soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=" +} +``` -### Update snippet -Updates an existing project snippet. +### Add deploy key + +Creates a new deploy key for a project. ``` -PUT /projects/:id/snippets/:snippet_id +POST /projects/:id/keys ``` Parameters: + `id` (required) - The ID of the project -+ `snippet_id` (required) - The id of the project snippet -+ `title` (optional) - The new title of the project snippet -+ `file_name` (optional) - The new file name of the project snippet -+ `lifetime` (optional) - The new expiration date of the snippet -+ `code` (optional) - The content of the snippet ++ `title` (required) - New deploy key's title ++ `key` (required) - New deploy key -## Delete snippet +### Delete deploy key -Deletes a project snippet. This is an idempotent function call and returns `200 Ok` -even if the snippet with the id is not available. +Delete a deploy key from a project ``` -DELETE /projects/:id/snippets/:snippet_id +DELETE /projects/:id/keys/:key_id ``` -Paramaters: +Parameters: + `id` (required) - The ID of the project -+ `snippet_id` (required) - The ID of the snippet ++ `key_id` (required) - The ID of the deploy key diff --git a/doc/api/snippets.md b/doc/api/snippets.md index 4becc928b1f..04ea367d518 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -46,7 +46,7 @@ Parameters: ## Create new snippet -Creates a new project snippet. +Creates a new project snippet. The user must have permission to create new snippets. ``` POST /projects/:id/snippets @@ -61,9 +61,9 @@ Parameters: + `code` (required) - The content of a snippet -## Edit snippet +## Update snippet -Updates an existing project snippet. +Updates an existing project snippet. The user must have permission to change an existing snippet. ``` PUT /projects/:id/snippets/:snippet_id @@ -96,7 +96,7 @@ Parameters: ## Snippet content -Get a raw project snippet. +Returns the raw project snippet as plain text. ``` GET /projects/:id/snippets/:snippet_id/raw diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md new file mode 100644 index 00000000000..f6e11ed238e --- /dev/null +++ b/doc/api/system_hooks.md @@ -0,0 +1,47 @@ +All methods require admin authorization.
+
+## List system hooks
+
+Get list of system hooks
+
+```
+GET /hooks
+```
+
+Will return hooks with status `200 OK` on success, or `404 Not found` on fail.
+
+## Add new system hook hook
+
+```
+POST /hooks
+```
+
+Parameters:
+
++ `url` (required) - The hook URL
+
+Will return status `201 Created` on success, or `404 Not found` on fail.
+
+## Test system hook
+
+```
+GET /hooks/:id
+```
+
+Parameters:
+
++ `id` (required) - The ID of hook
+
+Will return hook with status `200 OK` on success, or `404 Not found` on fail.
+
+## Delete system hook
+
+```
+DELETE /hooks/:id
+```
+
+Parameters:
+
++ `id` (required) - The ID of hook
+
+Will return status `200 OK` on success, or `404 Not found` on fail.
\ No newline at end of file diff --git a/doc/api/users.md b/doc/api/users.md index 6d5c9d78412..dc31c10eb9d 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -235,6 +235,23 @@ Parameters: + `key` (required) - new SSH key +## Add SSH key for user + +Create new key owned by specified user. Available only for admin + +``` +POST /users/:id/keys +``` + +Parameters: + ++ `id` (required) - id of specified user ++ `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. + ## Delete SSH key Deletes key owned by currently authenticated user. This is an idempotent function and calling it on a key that is already diff --git a/doc/install/installation.md b/doc/install/installation.md index d0f586af6b4..51a8dcfb876 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -288,7 +288,7 @@ a different host, you can configure its connection string via the `config/resque.yml` file. # example - production: redis.example.tld:6379 + production: redis://redis.example.tld:6379 ## Custom SSH Connection |