summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/api/README.md42
-rw-r--r--doc/api/groups.md11
-rw-r--r--doc/api/issues.md32
-rw-r--r--doc/api/merge_requests.md20
-rw-r--r--doc/api/milestones.md16
-rw-r--r--doc/api/notes.md115
-rw-r--r--doc/api/projects.md257
-rw-r--r--doc/api/repositories.md31
-rw-r--r--doc/api/snippets.md41
-rw-r--r--doc/api/users.md67
10 files changed, 441 insertions, 191 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index 0618db7e369..f6c4e41b6cd 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -1,6 +1,6 @@
# 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:
diff --git a/doc/api/groups.md b/doc/api/groups.md
index 4cde66b1726..e9702ea2cd1 100644
--- a/doc/api/groups.md
+++ b/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
diff --git a/doc/api/issues.md b/doc/api/issues.md
index 0383b676073..a8ae7401b39 100644
--- a/doc/api/issues.md
+++ b/doc/api/issues.md
@@ -1,6 +1,7 @@
## 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
diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md
index 525c55d12c2..111c52112eb 100644
--- a/doc/api/merge_requests.md
+++ b/doc/api/merge_requests.md
@@ -1,6 +1,7 @@
## 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
{
diff --git a/doc/api/milestones.md b/doc/api/milestones.md
index 73d29afc37a..92a29cee954 100644
--- a/doc/api/milestones.md
+++ b/doc/api/milestones.md
@@ -1,6 +1,6 @@
## 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
+
diff --git a/doc/api/notes.md b/doc/api/notes.md
index a4ba2826076..4b57f636a01 100644
--- a/doc/api/notes.md
+++ b/doc/api/notes.md
@@ -1,4 +1,4 @@
-## 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
++ `note_id` (required) - The ID of a wall note
-### List issue notes
-Get a list of issue notes.
+### 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
++ `issue_id` (required) - The ID of a project issue
++ `note_id` (required) - The ID of an issue note
-## Single note
-### Single wall note
+### Create new issue note
-Get a wall 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
++ `issue_id` (required) - The ID of an issue
++ `body` (required) - The content of a note
-### Single issue note
-Get an issue 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
++ `snippet_id` (required) - The ID of a project snippet
+
-### Single snippet note
+### Get single snippet note
-Get a 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 new snippet note
-Create a new wall 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.
+## Merge Requests
-### New issue note
+### List all merge request notes
-Create a new issue note.
+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
++ `merge_request_id` (required) - The ID of a project merge request
-Will return created note with status `201 Created` on success, or `404 Not found` on fail.
-### New snippet note
+### Get single merge request note
-Create a new snippet 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.
diff --git a/doc/api/projects.md b/doc/api/projects.md
index 4cbefbb6189..d6a9a8854ca 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,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.
+**Project access levels**
-## Create project for user
+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 new project owned by user. Available only for admin
+
+### 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
++ `id` (required) - The ID or NAME of a project
++ `query` (optional) - Query string to search for members
+
-## Get project team member
+### Get project team member
-Get a 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
+### 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
@@ -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.
+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
+## Hooks
-Get list for project 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
++ `id` (required) - The ID or NAME of a project
-Will return hooks with status `200 OK` on success, or `404 Not found` on fail.
-## Get project hook
+### Get project hook
-Get hook for project
+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.
+```json
+{
+ "id": 1,
+ "url": "http://example.com/hook",
+ "created_at": "2012-10-12T17:04:47Z"
+}
+```
-## Add project hook
-Add hook to project
+### 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 project hook
-Edit hook for project
+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 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/: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.
+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.
-## List deploy keys
+## 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
++ `id` (required) - The ID of the project
++ `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
+### 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
++ `id` (required) - The ID of the project
++ `key_id` (required) - The ID of the deploy key
-Will return `200 OK` on success, or `404 Not Found` on fail.
diff --git a/doc/api/repositories.md b/doc/api/repositories.md
index fd0ef1f53eb..39a7b0ed779 100644
--- a/doc/api/repositories.md
+++ b/doc/api/repositories.md
@@ -1,4 +1,4 @@
-## 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 repository branch
-Protect a single project 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,9 @@ 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
++ `page`(optional) - The page with the commits (pagination)
++ `per_page` (optional) - The number of commits per page (pagination)
```json
[
@@ -235,6 +241,7 @@ Parameters:
]
```
+
## Raw blob content
Get the raw file contents for a file.
@@ -248,5 +255,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.
diff --git a/doc/api/snippets.md b/doc/api/snippets.md
index ceb8a63d06f..04ea367d518 100644
--- a/doc/api/snippets.md
+++ b/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 new snippet
-Create a new project 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 snippet
-Update 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
@@ -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
diff --git a/doc/api/users.md b/doc/api/users.md
index b75e84c6b96..dc31c10eb9d 100644
--- a/doc/api/users.md
+++ b/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
+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.
-Will return created user with status `200 OK` on success, or `404 Not
-found` on fail.
## 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.
View Lorry Controller Status