summaryrefslogtreecommitdiff
path: root/doc/api
diff options
context:
space:
mode:
Diffstat (limited to 'doc/api')
-rw-r--r--doc/api/README.md16
-rw-r--r--doc/api/environments.md2
-rw-r--r--doc/api/jobs.md38
-rw-r--r--doc/api/keys.md1
-rw-r--r--doc/api/namespaces.md4
-rw-r--r--doc/api/project_snippets.md3
-rw-r--r--doc/api/projects.md239
-rw-r--r--doc/api/session.md1
-rw-r--r--doc/api/users.md20
-rw-r--r--doc/api/wikis.md157
10 files changed, 265 insertions, 216 deletions
diff --git a/doc/api/README.md b/doc/api/README.md
index c2a08dcff07..6cbea29bda6 100644
--- a/doc/api/README.md
+++ b/doc/api/README.md
@@ -58,19 +58,11 @@ following locations:
- [Validate CI configuration](lint.md)
- [V3 to V4](v3_to_v4.md)
- [Version](version.md)
+- [Wikis](wikis.md)
## Road to GraphQL
-Going forward, we will start on moving to
-[GraphQL](http://graphql.org/learn/best-practices/) and deprecate the use of
-controller-specific endpoints. GraphQL has a number of benefits:
-
-1. We avoid having to maintain two different APIs.
-2. Callers of the API can request only what they need.
-3. It is versioned by default.
-
-It will co-exist with the current v4 REST API. If we have a v5 API, this should
-be a compatibility layer on top of GraphQL.
+We have changed our plans to move to GraphQL. After reviewing the GraphQL license, anything related to the Facebook BSD plus patent license will not be allowed at GitLab.
## Basic usage
@@ -246,8 +238,8 @@ The following table gives an overview of how the API functions generally behave.
| ------------ | ----------- |
| `GET` | Access one or more resources and return the result as JSON. |
| `POST` | Return `201 Created` if the resource is successfully created and return the newly created resource as JSON. |
-| `GET` / `PUT` / `DELETE` | Return `200 OK` if the resource is accessed, modified or deleted successfully. The (modified) result is returned as JSON. |
-| `DELETE` | Designed to be idempotent, meaning a request to a resource still returns `200 OK` even it was deleted before or is not available. The reasoning behind this, is that the user is not really interested if the resource existed before or not. |
+| `GET` / `PUT` | Return `200 OK` if the resource is accessed or modified successfully. The (modified) result is returned as JSON. |
+| `DELETE` | Returns `204 No Content` if the resuource was deleted successfully. |
The following table shows the possible return codes for API requests.
diff --git a/doc/api/environments.md b/doc/api/environments.md
index 5ca766bf87d..e8deb3e07e9 100644
--- a/doc/api/environments.md
+++ b/doc/api/environments.md
@@ -94,7 +94,7 @@ Example response:
## Delete an environment
-It returns `200` if the environment was successfully deleted, and `404` if the environment does not exist.
+It returns `204` if the environment was successfully deleted, and `404` if the environment does not exist.
```
DELETE /projects/:id/environments/:environment_id
diff --git a/doc/api/jobs.md b/doc/api/jobs.md
index 297115e94ac..d60c7c12881 100644
--- a/doc/api/jobs.md
+++ b/doc/api/jobs.md
@@ -320,11 +320,11 @@ Response:
[ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893
-## Download the artifacts file
+## Download the artifacts archive
> [Introduced][ce-5347] in GitLab 8.10.
-Download the artifacts file from the given reference name and job provided the
+Download the artifacts archive from the given reference name and job provided the
job finished successfully.
```
@@ -354,6 +354,40 @@ Example response:
[ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347
+## Download a single artifact file
+
+> Introduced in GitLab 10.0
+
+Download a single artifact file from within the job's artifacts archive.
+
+Only a single file is going to be extracted from the archive and streamed to a client.
+
+```
+GET /projects/:id/jobs/:job_id/artifacts/*artifact_path
+```
+
+Parameters
+
+| Attribute | Type | Required | Description |
+|-----------------|---------|----------|-------------------------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `job_id ` | integer | yes | The unique job identifier |
+| `artifact_path` | string | yes | Path to a file inside the artifacts archive |
+
+Example request:
+
+```
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/jobs/5/artifacts/some/release/file.pdf"
+```
+
+Example response:
+
+| Status | Description |
+|-----------|--------------------------------------|
+| 200 | Sends a single artifact file |
+| 400 | Invalid path provided |
+| 404 | Build not found or no file/artifacts |
+
## Get a trace file
Get a trace of a specific job of a project
diff --git a/doc/api/keys.md b/doc/api/keys.md
index 376ac27df3a..ddcf7830621 100644
--- a/doc/api/keys.md
+++ b/doc/api/keys.md
@@ -32,6 +32,7 @@ Parameters:
"twitter": "",
"website_url": "",
"email": "john@example.com",
+ "theme_id": 2,
"color_scheme_id": 1,
"projects_limit": 10,
"current_sign_in_at": null,
diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md
index 8133251dffe..5c0bebbaeb0 100644
--- a/doc/api/namespaces.md
+++ b/doc/api/namespaces.md
@@ -28,12 +28,14 @@ Example response:
[
{
"id": 1,
+ "name": "user1",
"path": "user1",
"kind": "user",
"full_path": "user1"
},
{
"id": 2,
+ "name": "group1",
"path": "group1",
"kind": "group",
"full_path": "group1",
@@ -42,6 +44,7 @@ Example response:
},
{
"id": 3,
+ "name": "bar",
"path": "bar",
"kind": "group",
"full_path": "foo/bar",
@@ -77,6 +80,7 @@ Example response:
[
{
"id": 4,
+ "name": "twitter",
"path": "twitter",
"kind": "group",
"full_path": "twitter",
diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md
index 24c8ff5fa7a..ad2521230e6 100644
--- a/doc/api/project_snippets.md
+++ b/doc/api/project_snippets.md
@@ -95,8 +95,7 @@ Parameters:
## Delete snippet
-Deletes an existing project snippet. This is an idempotent function and deleting a non-existent
-snippet still returns a `200 OK` status code.
+Deletes an existing project snippet. This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
```
DELETE /projects/:id/snippets/:snippet_id
diff --git a/doc/api/projects.md b/doc/api/projects.md
index d3f8e509612..3144220e588 100644
--- a/doc/api/projects.md
+++ b/doc/api/projects.md
@@ -1,6 +1,6 @@
# Projects API
-### Project visibility level
+## Project visibility level
Project in GitLab can be either private, internal or public.
This is determined by the `visibility` field in the project.
@@ -16,16 +16,15 @@ Values for the project visibility level are:
* `public`:
The project can be cloned without any authentication.
-## List projects
+## List all projects
-Get a list of visible projects for authenticated user. When accessed without authentication, only public projects are returned.
+Get a list of all visible projects across GitLab for the authenticated user.
+When accessed without authentication, only public projects are returned.
```
GET /projects
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `archived` | boolean | no | Limit by archived status |
@@ -70,6 +69,7 @@ Parameters:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -137,6 +137,7 @@ Parameters:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -191,16 +192,15 @@ Parameters:
]
```
-### List a user's projects
+## List user projects
-Get a list of visible projects for the given user. When accessed without authentication, only public projects are returned.
+Get a list of visible projects for the given user. When accessed without
+authentication, only public projects are returned.
```
GET /users/:user_id/projects
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `user_id` | string | yes | The ID or username of the user |
@@ -246,6 +246,7 @@ Parameters:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -313,6 +314,7 @@ Parameters:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -367,7 +369,7 @@ Parameters:
]
```
-### Get single project
+## Get single project
Get a specific project. This endpoint can be accessed without authentication if
the project is publicly accessible.
@@ -376,8 +378,6 @@ the project is publicly accessible.
GET /projects/:id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -411,6 +411,7 @@ Parameters:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -480,17 +481,14 @@ Parameters:
Get the users list of a project.
-
-Parameters:
+```
+GET /projects/:id/users
+```
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `search` | string | no | Search for specific users |
-```
-GET /projects/:id/users
-```
-
```json
[
{
@@ -512,11 +510,11 @@ GET /projects/:id/users
]
```
-### Get project events
+## Get project events
-Please refer to the [Events API documentation](events.md#list-a-projects-visible-events)
+Please refer to the [Events API documentation](events.md#list-a-projects-visible-events).
-### Create project
+## Create project
Creates a new project owned by the authenticated user.
@@ -524,8 +522,6 @@ Creates a new project owned by the authenticated user.
POST /projects
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. |
@@ -537,6 +533,7 @@ Parameters:
| `jobs_enabled` | boolean | no | Enable jobs for this project |
| `wiki_enabled` | boolean | no | Enable wiki for this project |
| `snippets_enabled` | boolean | no | Enable snippets for this project |
+| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
@@ -551,7 +548,7 @@ Parameters:
| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
| `ci_config_path` | string | no | The path to CI config file |
-### Create project for user
+## Create project for user
Creates a new project owned by the specified user. Available only for admins.
@@ -559,8 +556,6 @@ Creates a new project owned by the specified user. Available only for admins.
POST /projects/user/:user_id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `user_id` | integer | yes | The user ID of the project owner |
@@ -574,6 +569,7 @@ Parameters:
| `jobs_enabled` | boolean | no | Enable jobs for this project |
| `wiki_enabled` | boolean | no | Enable wiki for this project |
| `snippets_enabled` | boolean | no | Enable snippets for this project |
+| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
@@ -588,7 +584,7 @@ Parameters:
| `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line |
| `ci_config_path` | string | no | The path to CI config file |
-### Edit project
+## Edit project
Updates an existing project.
@@ -596,8 +592,6 @@ Updates an existing project.
PUT /projects/:id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -610,6 +604,7 @@ Parameters:
| `jobs_enabled` | boolean | no | Enable jobs for this project |
| `wiki_enabled` | boolean | no | Enable wiki for this project |
| `snippets_enabled` | boolean | no | Enable snippets for this project |
+| `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push |
| `container_registry_enabled` | boolean | no | Enable container registry for this project |
| `shared_runners_enabled` | boolean | no | Enable shared runners for this project |
| `visibility` | string | no | See [project visibility level](#project-visibility-level) |
@@ -623,24 +618,24 @@ Parameters:
| `avatar` | mixed | no | Image file for avatar of the project |
| `ci_config_path` | string | no | The path to CI config file |
-### Fork project
+## Fork project
Forks a project into the user namespace of the authenticated user or the one provided.
-The forking operation for a project is asynchronous and is completed in a background job. The request will return immediately. To determine whether the fork of the project has completed, query the `import_status` for the new project.
+The forking operation for a project is asynchronous and is completed in a
+background job. The request will return immediately. To determine whether the
+fork of the project has completed, query the `import_status` for the new project.
```
POST /projects/:id/fork
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
| `namespace` | integer/string | yes | The ID or path of the namespace that the project will be forked to |
-### Star a project
+## Star a project
Stars a given project. Returns status code `304` if the project is already starred.
@@ -648,8 +643,6 @@ Stars a given project. Returns status code `304` if the project is already starr
POST /projects/:id/star
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -683,6 +676,7 @@ Example response:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -717,7 +711,7 @@ Example response:
}
```
-### Unstar a project
+## Unstar a project
Unstars a given project. Returns status code `304` if the project is not starred.
@@ -758,6 +752,7 @@ Example response:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -792,7 +787,7 @@ Example response:
}
```
-### Archive a project
+## Archive a project
Archives the project if the user is either admin or the project owner of this project. This action is
idempotent, thus archiving an already archived project will not change the project.
@@ -839,6 +834,7 @@ Example response:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -885,7 +881,7 @@ Example response:
}
```
-### Unarchive a project
+## Unarchive a project
Unarchives the project if the user is either admin or the project owner of this project. This action is
idempotent, thus unarchiving an non-archived project will not change the project.
@@ -932,6 +928,7 @@ Example response:
"jobs_enabled": true,
"wiki_enabled": true,
"snippets_enabled": false,
+ "resolve_outdated_diff_discussions": false,
"container_registry_enabled": false,
"created_at": "2013-09-30T13:46:02Z",
"last_activity_at": "2013-09-30T13:46:02Z",
@@ -978,7 +975,7 @@ Example response:
}
```
-### Remove project
+## Remove project
Removes a project including all associated resources (issues, merge requests etc.)
@@ -986,15 +983,11 @@ Removes a project including all associated resources (issues, merge requests etc
DELETE /projects/:id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-## Uploads
-
-### Upload a file
+## Upload a file
Uploads a file to the specified project to be used in an issue or merge request description, or a comment.
@@ -1002,8 +995,6 @@ Uploads a file to the specified project to be used in an issue or merge request
POST /projects/:id/uploads
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1028,15 +1019,11 @@ Returned object:
}
```
-**Note**: The returned `url` is relative to the project path.
+>**Note**: The returned `url` is relative to the project path.
In Markdown contexts, the link is automatically expanded when the format in
`markdown` is used.
-## Project members
-
-Please consult the [Project Members](members.md) documentation.
-
-### Share project with group
+## Share project with group
Allow to share project with group.
@@ -1044,8 +1031,6 @@ Allow to share project with group.
POST /projects/:id/share
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1053,7 +1038,7 @@ Parameters:
| `group_access` | integer | yes | The permissions level to grant the group |
| `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 |
-### Delete a shared project link within a group
+## Delete a shared project link within a group
Unshare the project from the group. Returns `204` and no content on success.
@@ -1061,8 +1046,6 @@ Unshare the project from the group. Returns `204` and no content on success.
DELETE /projects/:id/share/:group_id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1085,8 +1068,6 @@ Get a list of project hooks.
GET /projects/:id/hooks
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1099,8 +1080,6 @@ Get a specific hook for a project.
GET /projects/:id/hooks/:hook_id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1132,8 +1111,6 @@ Adds a hook to a specified project.
POST /projects/:id/hooks
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1157,8 +1134,6 @@ Edits a hook for a specified project.
PUT /projects/:id/hooks/:hook_id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1184,8 +1159,6 @@ Either the hook is available or not.
DELETE /projects/:id/hooks/:hook_id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1194,126 +1167,16 @@ Parameters:
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
-
-For more information please consult the [Branches](branches.md) documentation.
-
-### List branches
-
-Lists all branches of a project.
-
-```
-GET /projects/:id/repository/branches
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-
-```json
-[
- {
- "name": "async",
- "commit": {
- "id": "a2b702edecdf41f07b42653eb1abe30ce98b9fca",
- "parent_ids": [
- "3f94fc7c85061973edc9906ae170cc269b07ca55"
- ],
- "message": "give Caolan credit where it's due (up top)",
- "author_name": "Jeremy Ashkenas",
- "author_email": "jashkenas@example.com",
- "authored_date": "2010-12-08T21:28:50+00:00",
- "committer_name": "Jeremy Ashkenas",
- "committer_email": "jashkenas@example.com",
- "committed_date": "2010-12-08T21:28:50+00:00"
- },
- "protected": false,
- "developers_can_push": false,
- "developers_can_merge": false
- },
- {
- "name": "gh-pages",
- "commit": {
- "id": "101c10a60019fe870d21868835f65c25d64968fc",
- "parent_ids": [
- "9c15d2e26945a665131af5d7b6d30a06ba338aaa"
- ],
- "message": "Underscore.js 1.5.2",
- "author_name": "Jeremy Ashkenas",
- "author_email": "jashkenas@example.com",
- "authored_date": "2013-09-07T12:58:21+00:00",
- "committer_name": "Jeremy Ashkenas",
- "committer_email": "jashkenas@example.com",
- "committed_date": "2013-09-07T12:58:21+00:00"
- },
- "protected": false,
- "developers_can_push": false,
- "developers_can_merge": false
- }
-]
-```
-
-### Single branch
-
-A specific branch of a project.
-
-```
-GET /projects/:id/repository/branches/:branch
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-| `branch` | string | yes | The name of the branch |
-| `developers_can_push` | boolean | no | Flag if developers can push to the branch |
-| `developers_can_merge` | boolean | no | Flag if developers can merge to the branch |
-
-### Protect single branch
-
-Protects a single branch of a project.
-
-```
-PUT /projects/:id/repository/branches/:branch/protect
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-| `branch` | string | yes | The name of the branch |
-
-### Unprotect single branch
-
-Unprotects a single branch of a project.
-
-```
-PUT /projects/:id/repository/branches/:branch/unprotect
-```
-
-Parameters:
-
-| Attribute | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
-| `branch` | string | yes | The name of the branch |
-
## Admin fork relation
Allows modification of the forked relationship between existing projects. Available only for admins.
-### Create a forked from/to relation between existing projects.
+### Create a forked from/to relation between existing projects
```
POST /projects/:id/fork/:forked_from_id
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1325,8 +1188,6 @@ Parameters:
DELETE /projects/:id/fork
```
-Parameter:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
@@ -1341,8 +1202,6 @@ accessible.
GET /projects
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `search` | string | yes | A string contained in the project name |
@@ -1355,14 +1214,20 @@ curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/a
## Start the Housekeeping task for a Project
->**Note:** This feature was introduced in GitLab 9.0
+> Introduced in GitLab 9.0.
```
POST /projects/:id/housekeeping
```
-Parameters:
-
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
-| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+
+## Branches
+
+Read more in the [Branches](branches.md) documentation.
+
+## Project members
+
+Read more in the [Project members](members.md) documentation.
diff --git a/doc/api/session.md b/doc/api/session.md
index f79eac11689..b97e26f34a2 100644
--- a/doc/api/session.md
+++ b/doc/api/session.md
@@ -39,6 +39,7 @@ Example response:
"twitter": "",
"website_url": "",
"email": "john@example.com",
+ "theme_id": 1,
"color_scheme_id": 1,
"projects_limit": 10,
"current_sign_in_at": "2015-07-07T07:10:58.392Z",
diff --git a/doc/api/users.md b/doc/api/users.md
index 57b4e117cf3..6d5db16b36a 100644
--- a/doc/api/users.md
+++ b/doc/api/users.md
@@ -72,6 +72,7 @@ GET /users
"organization": "",
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
+ "theme_id": 1,
"last_activity_on": "2012-05-23",
"color_scheme_id": 2,
"projects_limit": 100,
@@ -105,6 +106,7 @@ GET /users
"organization": "",
"last_sign_in_at": null,
"confirmed_at": "2012-05-30T16:53:06.148Z",
+ "theme_id": 1,
"last_activity_on": "2012-05-23",
"color_scheme_id": 3,
"projects_limit": 100,
@@ -215,6 +217,7 @@ Parameters:
"organization": "",
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
+ "theme_id": 1,
"last_activity_on": "2012-05-23",
"color_scheme_id": 2,
"projects_limit": 100,
@@ -299,10 +302,7 @@ e.g. when renaming the email address to some existing one.
## User deletion
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.
+This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
```
DELETE /users/:id
@@ -344,6 +344,7 @@ GET /user
"organization": "",
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
+ "theme_id": 1,
"last_activity_on": "2012-05-23",
"color_scheme_id": 2,
"projects_limit": 100,
@@ -390,6 +391,7 @@ GET /user
"organization": "",
"last_sign_in_at": "2012-06-01T11:41:01Z",
"confirmed_at": "2012-05-23T09:05:22Z",
+ "theme_id": 1,
"last_activity_on": "2012-05-23",
"color_scheme_id": 2,
"projects_limit": 100,
@@ -524,8 +526,7 @@ Parameters:
## Delete SSH key for current 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`.
+This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
```
DELETE /user/keys/:key_id
@@ -548,8 +549,6 @@ Parameters:
- `id` (required) - id of specified user
- `key_id` (required) - SSH key ID
-Will return `200 OK` on success, or `404 Not found` if either user or key cannot be found.
-
## List all GPG keys
Get a list of currently authenticated user's GPG keys.
@@ -865,8 +864,7 @@ Parameters:
## Delete email for current user
Deletes email owned by currently authenticated user.
-This is an idempotent function and calling it on a email that is already deleted
-or not available results in `200 OK`.
+This returns a `204 No Content` status code if the operation was successfully or `404` if the resource was not found.
```
DELETE /user/emails/:email_id
@@ -889,8 +887,6 @@ Parameters:
- `id` (required) - id of specified user
- `email_id` (required) - email ID
-Will return `200 OK` on success, or `404 Not found` if either user or email cannot be found.
-
## Block user
Blocks the specified user. Available only for admin.
diff --git a/doc/api/wikis.md b/doc/api/wikis.md
new file mode 100644
index 00000000000..10eebc4a3c1
--- /dev/null
+++ b/doc/api/wikis.md
@@ -0,0 +1,157 @@
+# Wikis API
+
+> [Introduced][ce-13372] in GitLab 10.0.
+
+Available only in APIv4.
+
+## List wiki pages
+
+Get all wiki pages for a given project.
+
+```
+GET /projects/:id/wikis
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ------- | -------- | --------------------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `with_content` | boolean | no | Include pages' content |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1
+```
+
+Example response:
+
+```json
+[
+ {
+ "content" : "Here is an instruction how to deploy this project.",
+ "format" : "markdown",
+ "slug" : "deploy",
+ "title" : "deploy"
+ },
+ {
+ "content" : "Our development process is described here.",
+ "format" : "markdown",
+ "slug" : "development",
+ "title" : "development"
+ },{
+ "content" : "* [Deploy](deploy)\n* [Development](development)",
+ "format" : "markdown",
+ "slug" : "home",
+ "title" : "home"
+ }
+]
+```
+
+## Get a wiki page
+
+Get a wiki page for a given project.
+
+```
+GET /projects/:id/wikis/:slug
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ------- | -------- | --------------------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `slug` | string | yes | The slug (a unique string) of the wiki page |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/wikis/home
+```
+
+Example response:
+
+```json
+[
+ {
+ "content" : "home page",
+ "format" : "markdown",
+ "slug" : "home",
+ "title" : "home"
+ }
+]
+```
+
+## Create a new wiki page
+
+Creates a new wiki page for the given repository with the given title, slug, and content.
+
+```
+POST /projects/:id/wikis
+```
+
+| Attribute | Type | Required | Description |
+| ------------- | ------- | -------- | ---------------------------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `content` | string | yes | The content of the wiki page |
+| `title` | string | yes | The title of the wiki page |
+| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` |
+
+```bash
+curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis"
+```
+
+Example response:
+
+```json
+{
+ "content" : "Hello world",
+ "format" : "markdown",
+ "slug" : "Hello",
+ "title" : "Hello"
+}
+```
+
+## Edit an existing wiki page
+
+Updates an existing wiki page. At least one parameter is required to update the wiki page.
+
+```
+PUT /projects/:id/wikis/:slug
+```
+
+| Attribute | Type | Required | Description |
+| --------------- | ------- | --------------------------------- | ------------------------------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `content` | string | yes if `title` is not provided | The content of the wiki page |
+| `title` | string | yes if `content` is not provided | The title of the wiki page |
+| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` |
+| `slug` | string | yes | The slug (a unique string) of the wiki page |
+
+
+```bash
+curl --request PUT --data "format=rdoc&content=documentation&title=Docs" --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
+```
+
+Example response:
+
+```json
+{
+ "content" : "documentation",
+ "format" : "markdown",
+ "slug" : "Docs",
+ "title" : "Docs"
+}
+```
+
+## Delete a wiki page
+
+Deletes a wiki page with a given slug.
+
+```
+DELETE /projects/:id/wikis/:slug
+```
+
+| Attribute | Type | Required | Description |
+| --------- | ------- | -------- | --------------------- |
+| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) |
+| `slug` | string | yes | The slug (a unique string) of the wiki page |
+
+```bash
+curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
+```
+
+On success the HTTP status code is `204` and no JSON response is expected.
View Lorry Controller Status