Skip to content

G
gitlab-ce
Commit 21b9829d authored by meziantou's avatar meziantou Committed by Rémy Coutable
Browse files
Options

Normalize API parameters 

Changelog: other
Signed-off-by: default avatarRémy Coutable <remy@rymai.me>
parent 0c5be42c
Show whitespace changes
Inline Side-by-side
Showing with 326 additions and 241 deletions
doc/api/dora4_project_analytics.md
View file @ 21b9829d
......@@ -25,9 +25,6 @@ GET /projects/:id/analytics/deployment_frequency?environment=:environment&from=:
| Attribute | Type | Required | Description |
|--------------|--------|----------|-----------------------|
| `id` | string | yes | The ID of the project |
| Parameter | Type | Required | Description |
|--------------|--------|----------|-----------------------|
| `environment`| string | yes | The name of the environment to filter by |
| `from` | string | yes | Datetime range to start from, inclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
| `to` | string | no | Datetime range to end at, exclusive, ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
......
doc/api/epics.md
View file @ 21b9829d
......@@ -62,7 +62,7 @@ GET /groups/:id/epics?state=opened
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `author_id` | integer | no | Return epics created by the given user `id` |
| `labels` | string | no | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used |
| `labels` | string | no | Return epics matching a comma-separated list of labels names. Label names from the epic group or a parent group can be used |
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Available in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) and later |
| `order_by` | string | no | Return epics ordered by `created_at`, `updated_at`, or `title` fields. Default is `created_at` |
| `sort` | string | no | Return epics sorted in `asc` or `desc` order. Default is `desc` |
......@@ -265,7 +265,7 @@ POST /groups/:id/epics
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `title` | string | yes | The title of the epic |
| `labels` | string | no | The comma separated list of labels |
| `labels` | string | no | The comma-separated list of labels |
| `description` | string | no | The description of the epic. Limited to 1,048,576 characters. |
| `confidential` | boolean | no | Whether the epic should be confidential |
| `created_at` | string | no | When the epic was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z` . Requires administrator or project/group owner privileges ([available](https://gitlab.com/gitlab-org/gitlab/-/issues/255309) in GitLab 13.5 and later) |
......
doc/api/feature_flag_user_lists.md
View file @ 21b9829d
......@@ -71,7 +71,7 @@ POST /projects/:id/feature_flags_user_lists
| ------------------- | ---------------- | ---------- | ---------------------------------------------------------------------------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). |
| `name` | string | yes | The name of the feature flag. |
| `user_xids` | string | yes | A comma separated list of user IDs. |
| `user_xids` | string | yes | A comma-separated list of user IDs. |
```shell
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists" \
......@@ -143,7 +143,7 @@ PUT /projects/:id/feature_flags_user_lists/:iid
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). |
| `iid` | integer/string | yes | The internal ID of the project's feature flag user list. |
| `name` | string | no | The name of the feature flag. |
| `user_xids` | string | no | A comma separated list of user IDs. |
| `user_xids` | string | no | A comma-separated list of user IDs. |
```shell
curl "https://gitlab.example.com/api/v4/projects/1/feature_flags_user_lists/1" \
......
doc/api/group_labels.md
View file @ 21b9829d
......@@ -77,7 +77,7 @@ GET /groups/:id/labels/:label_id
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
| `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. |
| `include_descendant_groups` | boolean | no | Include descendant groups. Defaults to `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259024) in GitLab 13.6 |
......@@ -152,7 +152,7 @@ PUT /groups/:id/labels/:label_id
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
| `new_name` | string | no | The new name of the label |
| `color` | string | no | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
......@@ -193,7 +193,7 @@ DELETE /groups/:id/labels/:label_id
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
```shell
......@@ -214,7 +214,7 @@ POST /groups/:id/labels/:label_id/subscribe
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
```shell
......@@ -250,7 +250,7 @@ POST /groups/:id/labels/:label_id/unsubscribe
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
```shell
......
doc/api/instance_clusters.md
View file @ 21b9829d
......@@ -97,7 +97,6 @@ Example response:
...
}
]
```
## Get a single instance cluster
......@@ -184,7 +183,6 @@ curl --header "Private-Token:<your_access_token>" "http://gitlab.example.com/api
-H "Accept:application/json" \
-H "Content-Type:application/json" \
-X POST --data '{"name":"cluster-3", "environment_scope":"production", "platform_kubernetes_attributes":{"api_url":"https://example.com", "token":"12345", "ca_cert":"-----BEGIN CERTIFICATE-----qpoeiXXZafCM0ZDJkZjM...-----END CERTIFICATE-----"}}'
```
Example response:
......@@ -255,7 +253,6 @@ Example request:
curl --header "Private-Token: <your_access_token>" "http://gitlab.example.com/api/v4/admin/clusters/9" \
-H "Content-Type:application/json" \
-X PUT --data '{"name":"update-cluster-name", "platform_kubernetes_attributes":{"api_url":"https://new-example.com","token":"new-token"}}'
```
Example response:
......@@ -290,7 +287,6 @@ Example response:
"management_project": null,
"project": null
}
```
## Delete instance cluster
......
doc/api/labels.md
View file @ 21b9829d
......@@ -119,7 +119,7 @@ GET /projects/:id/labels/:label_id
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a project's label. |
| `include_ancestor_groups` | boolean | no | Include ancestor groups. Defaults to `true`. |
......@@ -195,7 +195,7 @@ DELETE /projects/:id/labels/:label_id
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
```shell
......@@ -216,7 +216,7 @@ PUT /projects/:id/labels/:label_id
| Attribute | Type | Required | Description |
| --------------- | ------- | --------------------------------- | ------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
| `new_name` | string | yes if `color` is not provided | The new name of the label |
| `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (for example, #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) |
......@@ -265,7 +265,7 @@ PUT /projects/:id/labels/:label_id/promote
| Attribute | Type | Required | Description |
| --------------- | ------- | --------------------------------- | ------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a group's label. |
```shell
......@@ -303,7 +303,7 @@ POST /projects/:id/labels/:label_id/subscribe
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a project's label |
```shell
......@@ -341,7 +341,7 @@ POST /projects/:id/labels/:label_id/unsubscribe
| Attribute | Type | Required | Description |
| ---------- | ----------------- | -------- | ------------------------------------ |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `label_id` | integer or string | yes | The ID or title of a project's label |
```shell
......
doc/api/merge_request_context_commits.md
View file @ 21b9829d
......@@ -17,8 +17,10 @@ GET /projects/:id/merge_requests/:merge_request_iid/context_commits
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `merge_request_iid` (required) - The internal ID of the merge request
| Attribute | Type | Required | Description |
|---------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `merge_request_iid` | integer | yes | The internal ID of the merge request |
```json
[
......@@ -49,8 +51,10 @@ POST /projects/:id/merge_requests/:merge_request_iid/context_commits
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `merge_request_iid` (required) - The internal ID of the merge request
| Attribute | Type | Required | Description |
|---------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `merge_request_iid` | integer | yes | The internal ID of the merge request |
```plaintext
POST /projects/:id/merge_requests/
......@@ -88,9 +92,8 @@ DELETE /projects/:id/merge_requests/:merge_request_iid/context_commits
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `merge_request_iid` (required) - The internal ID of the merge request
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
|---------------------|--------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `merge_request_iid` | integer | yes | The internal ID of the merge request |
| `commits` | string array | yes | The context commits' SHA |
doc/api/merge_requests.md
View file @ 21b9829d
......@@ -85,7 +85,7 @@ Parameters:
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. |
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. |
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. |
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
......@@ -272,7 +272,7 @@ Parameters:
| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc`. |
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. |
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. |
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`) |
......@@ -459,7 +459,7 @@ Parameters:
| `sort` | string | no | Return merge requests sorted in `asc` or `desc` order. Default is `desc`. |
| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. |
| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request. |
| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `labels` | string | no | Return merge requests matching a comma-separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. |
| `with_labels_details` | boolean | no | If `true`, response returns more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/21413) in GitLab 12.7.|
| `with_merge_status_recheck` | boolean | no | If `true`, this projection requests (but does not guarantee) that the `merge_status` field be recalculated asynchronously. Default is `false`. [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/31890) in GitLab 13.0. |
| `created_after` | datetime | no | Return merge requests created on or after the given time. Expected in ISO 8601 format (`2019-03-15T08:00:00Z`). |
......
doc/api/milestones.md
View file @ 21b9829d
......@@ -27,7 +27,7 @@ Parameters:
| Attribute | Type | Required | Description |
| ---------------------------- | ------ | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `iids[]` | integer array | optional | Return only the milestones having the given `iid` (Note: ignored if `include_parent_milestones` is set as `true`) |
| `state` | string | optional | Return only `active` or `closed` milestones |
| `title` | string | optional | Return only the milestones having the given `title` |
......@@ -68,8 +68,10 @@ GET /projects/:id/milestones/:milestone_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of the project's milestone
| Attribute | Type | Required | Description |
|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `milestone_id` | integer | yes | The ID of the project's milestone |
## Create new milestone
......@@ -81,11 +83,13 @@ POST /projects/:id/milestones
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `title` (required) - The title of a milestone
- `description` (optional) - The description of the milestone
- `due_date` (optional) - The due date of the milestone
- `start_date` (optional) - The start date of the milestone
| Attribute | Type | Required | Description |
|---------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `title` | string | yes | The title of a milestone |
| `description` | string | no | The description of the milestone |
| `due_date` | string | no | The due date of the milestone |
| `start_date` | string | no | The start date of the milestone |
## Edit milestone
......@@ -97,13 +101,15 @@ PUT /projects/:id/milestones/:milestone_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a project milestone
- `title` (optional) - The title of a milestone
- `description` (optional) - The description of a milestone
- `due_date` (optional) - The due date of the milestone
- `start_date` (optional) - The start date of the milestone
- `state_event` (optional) - The state event of the milestone (close or activate)
| Attribute | Type | Required | Description |
|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `milestone_id` | integer | yes | The ID of the project's milestone |
| `title` | string | no | The title of a milestone |
| `description` | string | no | The description of the milestone |
| `due_date` | string | no | The due date of the milestone |
| `start_date` | string | no | The start date of the milestone |
| `state_event` | string | no | The state event of the milestone (close or activate) |
## Delete project milestone
......@@ -115,8 +121,10 @@ DELETE /projects/:id/milestones/:milestone_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of the project's milestone
| Attribute | Type | Required | Description |
|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `milestone_id` | integer | yes | The ID of the project's milestone |
## Get all issues assigned to a single milestone
......@@ -128,8 +136,10 @@ GET /projects/:id/milestones/:milestone_id/issues
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a project milestone
| Attribute | Type | Required | Description |
|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `milestone_id` | integer | yes | The ID of the project's milestone |
## Get all merge requests assigned to a single milestone
......@@ -141,8 +151,10 @@ GET /projects/:id/milestones/:milestone_id/merge_requests
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a project milestone
| Attribute | Type | Required | Description |
|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `milestone_id` | integer | yes | The ID of the project's milestone |
## Promote project milestone to a group milestone
......@@ -156,8 +168,10 @@ POST /projects/:id/milestones/:milestone_id/promote
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a project milestone
| Attribute | Type | Required | Description |
|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `milestone_id` | integer | yes | The ID of the project's milestone |
## Get all burndown chart events for a single milestone **(PREMIUM)**
......@@ -172,5 +186,7 @@ GET /projects/:id/milestones/:milestone_id/burndown_events
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `milestone_id` (required) - The ID of a project milestone
| Attribute | Type | Required | Description |
|----------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `milestone_id` | integer | yes | The ID of the project's milestone |
doc/api/notes.md
View file @ 21b9829d
......@@ -54,7 +54,7 @@ GET /projects/:id/issues/:issue_iid/notes?sort=asc&order_by=updated_at
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
| `issue_iid` | integer | yes | The IID of an issue
| `sort` | string | no | Return issue notes sorted in `asc` or `desc` order. Default is `desc`
| `order_by` | string | no | Return issue notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
......@@ -120,9 +120,11 @@ GET /projects/:id/issues/:issue_iid/notes/:note_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `issue_iid` (required) - The IID of a project issue
- `note_id` (required) - The ID of an issue note
| Attribute | Type | Required | Description |
|-------------|----------------|----------|---------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `issue_iid` | integer | yes | The IID of a project issue |
| `note_id` | integer | yes | The ID of an issue note |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes/1"
......@@ -138,11 +140,13 @@ POST /projects/:id/issues/:issue_iid/notes
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `issue_iid` (required) - The IID of an issue
- `body` (required) - The content of a note. Limited to 1,000,000 characters.
- `confidential` (optional) - The confidential flag of a note. Default is false.
- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)
| Attribute | Type | Required | Description |
|----------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). |
| `issue_iid` | integer | yes | The IID of an issue. |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `confidential` | boolean | no | The confidential flag of a note. Default is false. |
| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
......@@ -158,11 +162,13 @@ PUT /projects/:id/issues/:issue_iid/notes/:note_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding).
- `issue_iid` (required) - The IID of an issue.
- `note_id` (required) - The ID of a note.
- `body` (optional) - The content of a note. Limited to 1,000,000 characters.
- `confidential` (optional) - The confidential flag of a note.
| Attribute | Type | Required | Description |
|----------------|----------------|----------|----------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding). |
| `issue_iid` | integer | yes | The IID of an issue. |
| `note_id` | integer | yes | The ID of a note. |
| `body` | string | no | The content of a note. Limited to 1,000,000 characters. |
| `confidential` | boolean | no | The confidential flag of a note. |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/issues/11/notes?body=note"
......@@ -180,7 +186,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `issue_iid` | integer | yes | The IID of an issue |
| `note_id` | integer | yes | The ID of a note |
......@@ -203,7 +209,7 @@ GET /projects/:id/snippets/:snippet_id/notes?sort=asc&order_by=updated_at
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
| `snippet_id` | integer | yes | The ID of a project snippet
| `sort` | string | no | Return snippet notes sorted in `asc` or `desc` order. Default is `desc`
| `order_by` | string | no | Return snippet notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
......@@ -222,9 +228,11 @@ GET /projects/:id/snippets/:snippet_id/notes/:note_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `snippet_id` (required) - The ID of a project snippet
- `note_id` (required) - The ID of a snippet note
| Attribute | Type | Required | Description |
|--------------|----------------|----------|---------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of a project snippet |
| `note_id` | integer | yes | The ID of a snippet note |
```json
{
......@@ -260,10 +268,12 @@ POST /projects/:id/snippets/:snippet_id/notes
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `snippet_id` (required) - The ID of a snippet
- `body` (required) - The content of a note. Limited to 1,000,000 characters.
- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)
| Attribute | Type | Required | Description |
|--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of a snippet |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippet/11/notes?body=note"
......@@ -279,10 +289,12 @@ PUT /projects/:id/snippets/:snippet_id/notes/:note_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `snippet_id` (required) - The ID of a snippet
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note. Limited to 1,000,000 characters.
| Attribute | Type | Required | Description |
|--------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a snippet note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/snippets/11/notes?body=note"
......@@ -300,7 +312,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `snippet_id` | integer | yes | The ID of a snippet |
| `note_id` | integer | yes | The ID of a note |
......@@ -321,7 +333,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes?sort=asc&order_by=upda
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
| `merge_request_iid` | integer | yes | The IID of a project merge request
| `sort` | string | no | Return merge request notes sorted in `asc` or `desc` order. Default is `desc`
| `order_by` | string | no | Return merge request notes ordered by `created_at` or `updated_at` fields. Default is `created_at`
......@@ -340,9 +352,11 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `merge_request_iid` (required) - The IID of a project merge request
- `note_id` (required) - The ID of a merge request note
| Attribute | Type | Required | Description |
|---------------------|----------------|----------|---------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `note_id` | integer | yes | The ID of a merge request note |
```json
{
......@@ -383,10 +397,12 @@ POST /projects/:id/merge_requests/:merge_request_iid/notes
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `merge_request_iid` (required) - The IID of a merge request
- `body` (required) - The content of a note. Limited to 1,000,000 characters.
- `created_at` (optional) - Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights)
| Attribute | Type | Required | Description |
|---------------------|----------------|----------|------------------------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
| `created_at` | string | no | Date time string, ISO 8601 formatted. Example: `2016-03-11T03:45:40Z` (requires administrator or project/group owner rights) |
### Modify existing merge request note
......@@ -398,10 +414,12 @@ PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding)
- `merge_request_iid` (required) - The IID of a merge request
- `note_id` (required) - The ID of a note
- `body` (required) - The content of a note. Limited to 1,000,000 characters.
| Attribute | Type | Required | Description |
|---------------------|----------------|----------|---------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a project merge request |
| `note_id` | integer | no | The ID of a note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/merge_requests/11/notes?body=note"
......@@ -419,7 +437,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | ---- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `merge_request_iid` | integer | yes | The IID of a merge request |
| `note_id` | integer | yes | The ID of a note |
......@@ -440,7 +458,7 @@ GET /groups/:id/epics/:epic_id/notes?sort=asc&order_by=updated_at
| Attribute | Type | Required | Description |
| ------------------- | ---------------- | ---------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of a group epic |
| `sort` | string | no | Return epic notes sorted in `asc` or `desc` order. Default is `desc` |
| `order_by` | string | no | Return epic notes ordered by `created_at` or `updated_at` fields. Default is `created_at` |
......@@ -461,7 +479,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
......@@ -502,7 +520,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
......@@ -522,7 +540,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
| `body` | string | yes | The content of a note. Limited to 1,000,000 characters. |
......@@ -543,7 +561,7 @@ Parameters:
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ----------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the group](index.md#namespaced-path-encoding) |
| `epic_id` | integer | yes | The ID of an epic |
| `note_id` | integer | yes | The ID of a note |
......
doc/api/oauth2.md
View file @ 21b9829d
......@@ -98,7 +98,7 @@ Before starting the flow, generate the `STATE`, the `CODE_VERIFIER` and the `COD
This page asks the user to approve the request from the app to access their
account based on the scopes specified in `REQUESTED_SCOPES`. The user is then
redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
is a space separated list of scopes associated with the user.
is a space-separated list of scopes associated with the user.
For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes.
The redirect includes the authorization `code`, for example:
......@@ -178,7 +178,7 @@ be used as a CSRF token.
This page asks the user to approve the request from the app to access their
account based on the scopes specified in `REQUESTED_SCOPES`. The user is then
redirected back to the specified `REDIRECT_URI`. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
is a space separated list of scopes associated with the user.
is a space-separated list of scopes associated with the user.
For example,`scope=read_user+profile` requests the `read_user` and `profile` scopes.
The redirect includes the authorization `code`, for example:
......@@ -266,7 +266,7 @@ https://gitlab.example.com/oauth/authorize?client_id=APP_ID&redirect_uri=REDIREC
This prompts the user to approve the applications access to their account
based on the scopes specified in `REQUESTED_SCOPES` and then redirect back to
the `REDIRECT_URI` you provided. The [scope parameter](https://github.com/doorkeeper-gem/doorkeeper/wiki/Using-Scopes#requesting-particular-scopes)
is a space separated list of scopes you want to have access to (for example, `scope=read_user+profile`
is a space-separated list of scopes you want to have access to (for example, `scope=read_user+profile`
would request `read_user` and `profile` scopes). The redirect
includes a fragment with `access_token` as well as token details in GET
parameters, for example:
......
doc/api/project_badges.md
View file @ 21b9829d
......@@ -11,7 +11,7 @@ type: reference, api
## Placeholder tokens
Badges support placeholders that are replaced in real time in both the link and image URL. The allowed placeholders are:
Badges support placeholders that are replaced in real-time in both the link and image URL. The allowed placeholders are:
<!-- vale gitlab.Spelling = NO -->
......
doc/api/project_clusters.md
View file @ 21b9829d
......@@ -384,7 +384,6 @@ Example response:
}
}
}
```
## Delete project cluster
......
doc/api/project_snippets.md
View file @ 21b9829d
......@@ -36,7 +36,9 @@ GET /projects/:id/snippets
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
| Attribute | Type | Required | Description |
|-----------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
## Single snippet
......@@ -48,8 +50,10 @@ GET /projects/:id/snippets/:snippet_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `snippet_id` (required) - The ID of a project's snippet
| Attribute | Type | Required | Description |
|--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `snippet_id` | integer | yes | The ID of a project's snippet |
```json
{
......@@ -85,7 +89,7 @@ Parameters:
| Attribute | Type | Required | Description |
|:------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `title` | string | yes | Title of a snippet |
| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file |
| `content` | string | no | Deprecated: Use `files` instead. Content of a snippet |
......@@ -132,7 +136,7 @@ Parameters:
| Attribute | Type | Required | Description |
|:----------------------|:----------------|:---------|:----------------------------------------------------------------------------------------------------------------|
| `id` | integer | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `snippet_id` | integer | yes | The ID of a project's snippet |
| `title` | string | no | Title of a snippet |
| `file_name` | string | no | Deprecated: Use `files` instead. Name of a snippet file |
......@@ -183,8 +187,10 @@ DELETE /projects/:id/snippets/:snippet_id
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `snippet_id` (required) - The ID of a project's snippet
| Attribute | Type | Required | Description |
|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `snippet_id` | integer | yes | The ID of a project's snippet |
Example request:
......@@ -203,8 +209,10 @@ GET /projects/:id/snippets/:snippet_id/raw
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `snippet_id` (required) - The ID of a project's snippet
| Attribute | Type | Required | Description |
|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `snippet_id` | integer | yes | The ID of a project's snippet |
Example request:
......@@ -223,10 +231,12 @@ GET /projects/:id/snippets/:snippet_id/files/:ref/:file_path/raw
Parameters:
- `id` (required) - The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
- `snippet_id` (required) - The ID of a project's snippet
- `ref` (required) - The name of a branch, tag or commit, such as `main`
- `file_path` (required) - The URL-encoded path to the file, such as `snippet%2Erb`
| Attribute | Type | Required | Description |
|:-------------|:---------------|:---------|:----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `snippet_id` | integer | yes | The ID of a project's snippet |
| `ref` | string | yes | The name of a branch, tag or commit e.g. master |
| `file_path` | string | yes | The URL-encoded path to the file, e.g. snippet%2Erb |
Example request:
......@@ -246,8 +256,8 @@ GET /projects/:id/snippets/:snippet_id/user_agent_detail
```
| Attribute | Type | Required | Description |
|---------------|---------|----------|--------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of a project](index.md#namespaced-path-encoding). |
|--------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `snippet_id` | Integer | yes | The ID of a snippet |
Example request:
......
doc/api/project_statistics.md
View file @ 21b9829d
......@@ -21,7 +21,7 @@ GET /projects/:id/statistics
| Attribute | Type | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
Example response:
......
doc/api/project_templates.md
View file @ 21b9829d
......@@ -33,7 +33,7 @@ GET /projects/:id/templates/:type
| Attribute | Type | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `type` | string | yes | The type of the template. Accepted values are: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, `merge_requests` |
Example response (licenses):
......@@ -99,7 +99,7 @@ GET /projects/:id/templates/:type/:name
| Attribute | Type | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `id` | integer / string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `type` | string | yes| The type of the template. One of: `dockerfiles`, `gitignores`, `gitlab_ci_ymls`, `licenses`, `issues`, or `merge_requests`. |
| `name` | string | yes | The key of the template, as obtained from the collection endpoint |
| `source_template_project_id` | integer | no | The project ID where a given template is being stored. This is useful when multiple templates from different projects have the same name. If multiple templates have the same name, the match from `closest ancestor` is returned if `source_template_project_id` is not specified |
......
doc/api/projects.md
View file @ 21b9829d
......@@ -2477,8 +2477,8 @@ GET /projects/:id/push_rule
{
"id": 1,
"project_id": 3,
"commit_message_regex": "Fixes \d+\..*",
"commit_message_negative_regex": "ssh\:\/\/",
"commit_message_regex": "Fixes \\d+\\..*",
"commit_message_negative_regex": "ssh\\:\\/\\/",
"branch_name_regex": "",
"deny_delete_tag": false,
"created_at": "2012-10-12T17:04:47Z",
......
doc/api/protected_environments.md
View file @ 21b9829d
......@@ -117,13 +117,13 @@ Example response:
```json
{
"name":"production",
"deploy_access_levels":[
"name": "production",
"deploy_access_levels": [
{
"access_level":40,
"access_level_description":"protected-access-group",
"user_id":null,
"group_id":9899826
"access_level": 40,
"access_level_description": "protected-access-group",
"user_id": null,
"group_id": 9899826
}
]
}
......
doc/api/repositories.md
View file @ 21b9829d
......@@ -28,7 +28,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :---------- | :------------- | :------- | :---------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `path` | string | no | The path inside repository. Used to get content of subdirectories. |
| `ref` | string | no | The name of a repository branch or tag or if not given the default branch. |
| `recursive` | boolean | no | Boolean value used to get a recursive tree (false by default). |
......@@ -104,7 +104,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :-------- | :------------- | :------- | :---------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `sha` | string | yes | The blob SHA. |
## Raw blob content
......@@ -146,7 +146,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
|:------------|:---------------|:---------|:----------------------|
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `sha` | string | no | The commit SHA to download. A tag, branch reference, or SHA can be used. This defaults to the tip of the default branch if not specified. |
| `path` | string | no | The subpath of the repository to download. This defaults to the whole repository (empty string). |
......@@ -169,7 +169,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :--------- | :------------- | :------- | :---------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `from` | string | yes | The commit SHA or branch name. |
| `to` | string | yes | The commit SHA or branch name. |
| `from_project_id` | integer | no | The ID to compare from |
......@@ -231,7 +231,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
| :--------- | :------------- | :------- | :---------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
| `order_by` | string | no | Return contributors ordered by `name`, `email`, or `commits` (orders by commit date) fields. Default is `commits`. |
| `sort` | string | no | Return contributors sorted in `asc` or `desc` order. Default is `asc`. |
......@@ -263,7 +263,7 @@ GET /projects/:id/repository/merge_base
| Attribute | Type | Required | Description |
| --------- | -------------- | -------- | ------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
| `refs` | array | yes | The refs to find the common ancestor of, multiple refs can be passed |
Example request:
......
doc/api/repository_files.md
View file @ 21b9829d
......@@ -35,6 +35,12 @@ GET /projects/:id/repository/files/:file_path
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb?ref=master"
```
| Attribute | Type | Required | Description |
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `ref` | string | yes | The name of branch, tag or commit |
Example response:
```json
......@@ -52,11 +58,6 @@ Example response:
}
```
Parameters:
- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
- `ref` (required) - The name of branch, tag or commit
NOTE:
`blob_id` is the blob SHA, see [repositories - Get a blob from repository](repositories.md#get-a-blob-from-repository)
......@@ -95,6 +96,12 @@ Allows you to receive blame information. Each blame range contains lines and cor
GET /projects/:id/repository/files/:file_path/blame
```
| Attribute | Type | Required | Description |
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `ref` | string | yes | The name of branch, tag or commit |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/path%2Fto%2Ffile.rb/blame?ref=master"
```
......@@ -127,11 +134,6 @@ Example response:
]
```
Parameters:
- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
- `ref` (required) - The name of branch, tag or commit
NOTE:
`HEAD` method return just file metadata as in [Get file from repository](repository_files.md#get-file-from-repository).
......@@ -162,15 +164,16 @@ X-Gitlab-Size: 1476
GET /projects/:id/repository/files/:file_path/raw
```
| Attribute | Type | Required | Description |
|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `ref` | string | yes | The name of branch, tag or commit. Default is the `HEAD` of the project. |
```shell
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fmodels%2Fkey%2Erb/raw?ref=master"
```
Parameters:
- `file_path` (required) - URL encoded full path to new file, such as lib%2Fclass%2Erb.
- `ref` (optional) - The name of branch, tag or commit. Default is the `HEAD` of the project.
NOTE:
Like [Get file from repository](repository_files.md#get-file-from-repository) you can use `HEAD` to get just file metadata.
......@@ -182,6 +185,18 @@ This allows you to create a single file. For creating multiple files with a sing
POST /projects/:id/repository/files/:file_path
```
| Attribute | Type | Required | Description |
|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `branch` | string | yes | Name of the branch |
| `start_branch` | string | no | Name of the branch to start the new commit from |
| `encoding` | string | no | Change encoding to `base64`. Default is `text`. |
| `author_email` | string | no | Specify the commit author's email address |
| `author_name` | string | no | Specify the commit author's name |
| `content` | string | yes | File content |
| `commit_message` | string | yes | Commit message |
```shell
curl --request POST --header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
......@@ -199,17 +214,6 @@ Example response:
}
```
Parameters:
- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
- `branch` (required) - Name of the branch
- `start_branch` (optional) - Name of the branch to start the new commit from
- `encoding` (optional) - Change encoding to `base64`. Default is `text`.
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
- `content` (required) - File content
- `commit_message` (required) - Commit message
## Update existing file in repository
This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
......@@ -218,6 +222,19 @@ This allows you to update a single file. For updating multiple files with a sing
PUT /projects/:id/repository/files/:file_path
```
| Attribute | Type | Required | Description |
|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `branch` | string | yes | Name of the branch |
| `start_branch` | string | no | Name of the branch to start the new commit from |
| `encoding` | string | no | Change encoding to `base64`. Default is `text`. |
| `author_email` | string | no | Specify the commit author's email address |
| `author_name` | string | no | Specify the commit author's name |
| `content` | string | yes | File content |
| `commit_message` | string | yes | Commit message |
| `last_commit_id` | string | no | Last known file commit ID |
```shell
curl --request PUT --header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
......@@ -235,18 +252,6 @@ Example response:
}
```
Parameters:
- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
- `branch` (required) - Name of the branch
- `start_branch` (optional) - Name of the branch to start the new commit from
- `encoding` (optional) - Change encoding to `base64`. Default is `text`.
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
- `content` (required) - New file content
- `commit_message` (required) - Commit message
- `last_commit_id` (optional) - Last known file commit ID
If the commit fails for any reason we return a 400 error with a non-specific
error message. Possible causes for a failed commit include:
......@@ -265,6 +270,17 @@ This allows you to delete a single file. For deleting multiple files with a sing
DELETE /projects/:id/repository/files/:file_path
```
| Attribute | Type | Required | Description |
|------------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------|
| `id` | integer or string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user |
| `file_path` | string | yes | URL encoded full path to new file. Ex. `lib%2Fclass%2Erb`. |
| `branch` | string | yes | Name of the branch |
| `start_branch` | string | no | Name of the branch to start the new commit from |
| `author_email` | string | no | Specify the commit author's email address. |
| `author_name` | string | no | Specify the commit author's name. |
| `commit_message` | string | yes | Commit message. |
| `last_commit_id` | string | no | Last known file commit ID. |
```shell
curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \
--header "Content-Type: application/json" \
......@@ -272,13 +288,3 @@ curl --request DELETE --header 'PRIVATE-TOKEN: <your_access_token>' \
"commit_message": "delete file"}' \
"https://gitlab.example.com/api/v4/projects/13083/repository/files/app%2Fproject%2Erb"
```
Parameters:
- `file_path` (required) - URL encoded full path to new file. Ex. lib%2Fclass%2Erb
- `branch` (required) - Name of the branch
- `start_branch` (optional) - Name of the branch to start the new commit from
- `author_email` (optional) - Specify the commit author's email address
- `author_name` (optional) - Specify the commit author's name
- `commit_message` (required) - Commit message
- `last_commit_id` (optional) - Last known file commit ID
doc/api/users.md
View file @ 21b9829d
......@@ -269,7 +269,9 @@ GET /users/:id
Parameters:
- `id` (required) - The ID of a user
| Attribute | Type | Required | Description |
|-----------|---------|----------|------------------|
| `id` | integer | yes | The ID of a user |
```json
{
......@@ -303,7 +305,9 @@ GET /users/:id
Parameters:
- `id` (required) - The ID of a user
| Attribute | Type | Required | Description |
|-----------|---------|----------|------------------|
| `id` | integer | yes | The ID of a user |
Example Responses:
......@@ -509,8 +513,10 @@ DELETE /users/:id/identities/:provider
Parameters:
- `id` (required) - The ID of the user
- `provider` (required) - External provider name
| Attribute | Type | Required | Description |
|------------|---------|----------|------------------------|
| `id` | integer | yes | The ID of a user |
| `provider` | string | yes | External provider name |
## User deletion
......@@ -523,10 +529,10 @@ DELETE /users/:id
Parameters:
- `id` (required) - The ID of the user
- `hard_delete` (optional) - If true, contributions that would usually be
[moved to the ghost user](../user/profile/account/delete_account.md#associated-records)
are deleted instead, as well as groups owned solely by this user.
| Attribute | Type | Required | Description |
|---------------|---------|----------|----------------------------------------------|
| `id` | integer | yes | The ID of a user |
| `hard_delete` | boolean | no | If true, contributions that would usually be [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) are deleted instead, as well as groups owned solely by this user. |
## List current user (for normal users)
......@@ -576,14 +582,16 @@ GET /user
## List current user (for admins)
Parameters:
- `sudo` (optional) - the ID of a user to make the call in their place
```plaintext
GET /user
```
Parameters:
| Attribute | Type | Required | Description |
|-----------|---------|----------|--------------------------------------------------|
| `sudo` | integer | no | the ID of a user to make the call in their place |
```json
{
"id": 1,
......@@ -936,7 +944,9 @@ GET /user/keys/:key_id
Parameters:
- `key_id` (required) - The ID of an SSH key
| Attribute | Type | Required | Description |
|-----------|--------|----------|----------------------|
| `key_id` | string | yes | The ID of an SSH key |
```json
{
......@@ -957,9 +967,11 @@ POST /user/keys
Parameters:
- `title` (required) - new SSH key's title
- `key` (required) - new SSH key
- `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
| Attribute | Type | Required | Description |
|--------------|--------|----------|--------------------------------------------------------------------------------|
| `title` | string | yes | new SSH key's title |
| `key` | string | yes | new SSH key |
| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
```json
{
......@@ -995,10 +1007,12 @@ POST /users/:id/keys
Parameters:
- `id` (required) - ID of specified user
- `title` (required) - new SSH key's title
- `key` (required) - new SSH key
- `expires_at` (optional) - The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`)
| Attribute | Type | Required | Description |
|--------------|---------|----------|--------------------------------------------------------------------------------|
| `id` | integer | yes | ID of specified user |
| `title` | string | yes | new SSH key's title |
| `key` | string | yes | new SSH key |
| `expires_at` | string | no | The expiration date of the SSH key in ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`) |
NOTE:
This also adds an audit event, as described in [audit instance events](../administration/audit_events.md#instance-events). **(PREMIUM)**
......@@ -1014,7 +1028,9 @@ DELETE /user/keys/:key_id
Parameters:
- `key_id` (required) - SSH key ID
| Attribute | Type | Required | Description |
|-----------|---------|----------|-------------|
| `key_id` | integer | yes | SSH key ID |
## Delete SSH key for given user
......@@ -1026,8 +1042,10 @@ DELETE /users/:id/keys/:key_id
Parameters:
- `id` (required) - ID of specified user
- `key_id` (required) - SSH key ID
| Attribute | Type | Required | Description |
|-----------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
| `key_id` | integer | yes | SSH key ID |
## List all GPG keys
......@@ -1092,8 +1110,8 @@ POST /user/gpg_keys
Parameters:
| Attribute | Type | Required | Description |
| --------- | ------ | -------- | --------------- |
| key | string | yes | The new GPG key |
|-----------|--------|----------|-----------------|
| `key` | string | yes | The new GPG key |
```shell
curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." \
......@@ -1288,7 +1306,9 @@ GET /users/:id/emails
Parameters:
- `id` (required) - ID of specified user
| Attribute | Type | Required | Description |
|-----------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
## Single email
......@@ -1300,7 +1320,9 @@ GET /user/emails/:email_id
Parameters:
- `email_id` (required) - email ID
| Attribute | Type | Required | Description |
|------------|---------|----------|-------------|
| `email_id` | integer | yes | Email ID |
```json
{
......@@ -1320,7 +1342,9 @@ POST /user/emails
Parameters:
- `email` (required) - email address
| Attribute | Type | Required | Description |
|-----------|--------|----------|-------------|
| `email` | string | yes | Email address |
```json
{
......@@ -1353,9 +1377,11 @@ POST /users/:id/emails
Parameters:
- `id` (required) - ID of specified user
- `email` (required) - email address
- `skip_confirmation` (optional) - Skip confirmation and assume email is verified - true or false (default)
| Attribute | Type | Required | Description |
|---------------------|---------|----------|---------------------------------------------------------------------------|
| `id` | string | yes | ID of specified user |
| `email` | string | yes | Email address |
| `skip_confirmation` | boolean | no | Skip confirmation and assume email is verified - true or false (default) |
## Delete email for current user
......@@ -1368,7 +1394,9 @@ DELETE /user/emails/:email_id
Parameters:
- `email_id` (required) - email ID
| Attribute | Type | Required | Description |
|------------|---------|----------|-------------|
| `email_id` | integer | yes | Email ID |
## Delete email for given user
......@@ -1380,8 +1408,10 @@ DELETE /users/:id/emails/:email_id
Parameters:
- `id` (required) - ID of specified user
- `email_id` (required) - email ID
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
| `email_id` | integer | yes | Email ID |
## Block user
......@@ -1393,7 +1423,9 @@ POST /users/:id/block
Parameters:
- `id` (required) - ID of specified user
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
Returns:
......@@ -1413,7 +1445,9 @@ POST /users/:id/unblock
Parameters:
- `id` (required) - ID of specified user
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
Returns `201 OK` on success, `404 User Not Found` is user cannot be found or
`403 Forbidden` when trying to unblock a user blocked by LDAP synchronization.
......@@ -1430,7 +1464,9 @@ POST /users/:id/deactivate
Parameters:
- `id` (required) - ID of specified user
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
Returns:
......@@ -1453,7 +1489,9 @@ POST /users/:id/activate
Parameters:
- `id` (required) - ID of specified user
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
Returns:
......@@ -1572,7 +1610,9 @@ POST /users/:id/approve
Parameters:
- `id` (required) - ID of specified user
| Attribute | Type | Required | Description |
|------------|---------|----------|----------------------|
| `id` | integer | yes | ID of specified user |
```shell
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve"
......@@ -1731,10 +1771,6 @@ It revokes an impersonation token.
DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id
```
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"
```
Parameters:
| Attribute | Type | Required | Description |
......@@ -1742,6 +1778,10 @@ Parameters:
| `user_id` | integer | yes | The ID of the user |
| `impersonation_token_id` | integer | yes | The ID of the impersonation token |
```shell
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"
```
## Create a personal access token **(FREE SELF)**
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17176) in GitLab 13.6.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7