diff options
author | Oswaldo Ferreira <oswaldo@gitlab.com> | 2017-03-31 04:11:12 +0300 |
---|---|---|
committer | Oswaldo Ferreira <oswaldo@gitlab.com> | 2017-04-05 19:50:12 +0300 |
commit | 7cb907cc77f5b7fdc4a5b2acc094e1fa3b3b9f92 (patch) | |
tree | 5ba36dd36a7ec14253532d93f596b353831ecdd3 /doc/api | |
parent | 4dd841c95aea291544bf69e796a757ba82f06a77 (diff) |
Add "search" optional param and docs for V4
Notice that this param is being supported since V3, but we have not added the proper docs for it
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/issues.md | 142 |
1 files changed, 91 insertions, 51 deletions
diff --git a/doc/api/issues.md b/doc/api/issues.md index a19c965a8c3..5702cdcf3c1 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -26,16 +26,20 @@ GET /issues?labels=foo,bar&state=opened GET /issues?milestone=1.0.0 GET /issues?milestone=1.0.0&state=opened GET /issues?iids[]=42&iids[]=43 +GET /issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string| no | The milestone title | -| `iids` | Array[integer] | no | Return only the issues having the given `iid` | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `iids` | Array[integer] | no | Return only the issues having the given `iid` | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search issues against their `title` and `description` | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues @@ -104,17 +108,21 @@ GET /groups/:id/issues?labels=foo,bar&state=opened GET /groups/:id/issues?milestone=1.0.0 GET /groups/:id/issues?milestone=1.0.0&state=opened GET /groups/:id/issues?iids[]=42&iids[]=43 +GET /groups/:id/issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a group | -| `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `iids` | Array[integer] | no | Return only the issues having the given `iid` | -| `milestone` | string| no | The milestone title | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a group | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `iids` | Array[integer] | no | Return only the issues having the given `iid` | +| `milestone` | string | no | The milestone title | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search group issues against their `title` and `description` | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| ```bash @@ -184,17 +192,21 @@ GET /projects/:id/issues?labels=foo,bar&state=opened GET /projects/:id/issues?milestone=1.0.0 GET /projects/:id/issues?milestone=1.0.0&state=opened GET /projects/:id/issues?iids[]=42&iids[]=43 +GET /projects/:id/issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `iids` | Array[integer] | no | Return only the milestone having the given `iid` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string| no | The milestone title | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `iids` | Array[integer] | no | Return only the milestone having the given `iid` | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search project issues against their `title` and `description` | +|-------------+----------------+----------+-----------------------------------------------------------------------------------------------------------------------------| ```bash @@ -258,10 +270,12 @@ Get a single project issue. GET /projects/:id/issues/:issue_iid ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/41 @@ -323,19 +337,23 @@ Creates a new project issue. POST /projects/:id/issues ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `assignee_id` | integer | no | The ID of a user to assign issue | -| `milestone_id` | integer | no | The ID of a milestone to assign issue | -| `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values. | -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------| +| Attribute | Type | Required | Description | +|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer | yes | The ID of a project | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | +| `assignee_id` | integer | no | The ID of a user to assign issue | +| `milestone_id` | integer | no | The ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | +| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. | +| - | - | - | When passing a description or title, these values will take precedence over the default values. | +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion | +| - | - | - | as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +|-------------------------------------------+---------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug @@ -383,8 +401,9 @@ closed. PUT /projects/:id/issues/:issue_iid ``` +|----------------+---------+----------+------------------------------------------------------------------------------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|----------------+---------+----------+------------------------------------------------------------------------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `title` | string | no | The title of an issue | @@ -396,6 +415,7 @@ PUT /projects/:id/issues/:issue_iid | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | | `updated_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +|----------------+---------+----------+------------------------------------------------------------------------------------------------------------| ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85?state_event=close @@ -442,10 +462,12 @@ Only for admins and project owners. Soft deletes the issue in question. DELETE /projects/:id/issues/:issue_iid ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --request DELETE --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85 @@ -464,11 +486,13 @@ project, it will then be assigned to the issue that is being moved. POST /projects/:id/issues/:issue_iid/move ``` +|-----------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-----------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `to_project_id` | integer | yes | The ID of the new project | +|-----------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues/85/move @@ -520,10 +544,12 @@ is returned. POST /projects/:id/issues/:issue_iid/subscribe ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/subscribe @@ -575,10 +601,12 @@ status code `304` is returned. POST /projects/:id/issues/:issue_iid/unsubscribe ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/unsubscribe @@ -594,10 +622,12 @@ returned. POST /projects/:id/issues/:issue_iid/todo ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/todo @@ -685,11 +715,13 @@ Sets an estimated time of work for this issue. POST /projects/:id/issues/:issue_iid/time_estimate ``` +|-------------+---------+----------+------------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `duration` | string | yes | The duration in human format. e.g: 3h30m | +|-------------+---------+----------+------------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_estimate?duration=3h30m @@ -714,10 +746,12 @@ Resets the estimated time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_time_estimate ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_time_estimate @@ -742,11 +776,13 @@ Adds spent time for this issue POST /projects/:id/issues/:issue_iid/add_spent_time ``` +|-------------+---------+----------+------------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+------------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `duration` | string | yes | The duration in human format. e.g: 3h30m | +|-------------+---------+----------+------------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/add_spent_time?duration=1h @@ -771,10 +807,12 @@ Resets the total spent time for this issue to 0 seconds. POST /projects/:id/issues/:issue_iid/reset_spent_time ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/reset_spent_time @@ -797,10 +835,12 @@ Example response: GET /projects/:id/issues/:issue_iid/time_stats ``` +|-------------+---------+----------+--------------------------------------| | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +|-------------+---------+----------+--------------------------------------| | `id` | integer | yes | The ID of a project | | `issue_iid` | integer | yes | The internal ID of a project's issue | +|-------------+---------+----------+--------------------------------------| ```bash curl --request GET --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/issues/93/time_stats |