73c6477b7e
Previously, we used brackets to denote the tier badges, but this made Kramdown, the docs site Markdown renderer, show many warnings when building the site. This is now fixed by using parentheses instead of square brackets. This was caused by [PREMIUM] looking like a link to Kramdown, which couldn't find a URL there. See: - https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/484 - https://gitlab.com/gitlab-org/gitlab-ce/issues/63800
10 KiB
10 KiB
Epic Links API (ULTIMATE)
Note: This endpoint was introduced in GitLab 11.8.
Manages parent-child epic relationships.
Every API call to epic_links must be authenticated.
If a user is not a member of a group and the group is private, a GET request on that group will result to a 404 status code.
Epics are available only in the Ultimate/Gold tier. If the epics feature is not available, a 403 status code will be returned.
List epics related to a given epic
Gets all child epics of an epic.
GET /groups/:id/epics/:epic_iid/epics
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
epic_iid |
integer | yes | The internal ID of the epic. |
curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/epics/
Example response:
[
{
"id": 29,
"iid": 6,
"group_id": 1,
"parent_id": 5,
"title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"author": {
"id": 10,
"name": "Lu Mayer",
"username": "kam",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
"web_url": "http://localhost:3001/kam"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null,
"end_date": "2018-07-31",
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"labels": []
}
]
Assign a child epic
Creates an association between two epics, designating one as the parent epic and the other as the child epic. A parent epic can have multiple child epics. If the new child epic already belonged to another epic, it is unassigned from that previous parent.
POST /groups/:id/epics/:epic_iid/epics
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
epic_iid |
integer | yes | The internal ID of the epic. |
child_epic_id |
integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. |
curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/epics/6
Example response:
{
"id": 6,
"iid": 38,
"group_id": 1,
"parent_id": 5
"title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"author": {
"id": 10,
"name": "Lu Mayer",
"username": "kam",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
"web_url": "http://localhost:3001/kam"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null,
"end_date": "2018-07-31",
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"labels": []
}
Create and assign a child epic
Creates a a new epic and associates it with provided parent epic. The response is LinkedEpic object.
POST /groups/:id/epics/:epic_iid/epics
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user |
epic_iid |
integer | yes | The internal ID of the (future parent) epic. |
title |
string | yes | The title of a newly created epic. |
curl --header POST "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/5/epics?title=Newpic
Example response:
{
"id": 24,
"iid": 2,
"title": "child epic",
"group_id": 49,
"parent_id": 23,
"has_children": false,
"has_issues": false,
"reference": "&2",
"url": "http://localhost/groups/group16/-/epics/2",
"relation_url": "http://localhost/groups/group16/-/epics/1/links/24"
}
Re-order a child epic
PUT /groups/:id/epics/:epic_iid/epics/:child_epic_id
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user. |
epic_iid |
integer | yes | The internal ID of the epic. |
child_epic_id |
integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. |
move_before_id |
integer | no | The global ID of a sibling epic that should be placed before the child epic. |
move_after_id |
integer | no | The global ID of a sibling epic that should be placed after the child epic. |
curl --header PUT "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/4/epics/5
Example response:
[
{
"id": 29,
"iid": 6,
"group_id": 1,
"parent_id": 5,
"title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"author": {
"id": 10,
"name": "Lu Mayer",
"username": "kam",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
"web_url": "http://localhost:3001/kam"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null,
"end_date": "2018-07-31",
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"labels": []
}
]
Unassign a child epic
Unassigns a child epic from a parent epic.
DELETE /groups/:id/epics/:epic_iid/epics/:child_epic_id
| Attribute | Type | Required | Description |
|---|---|---|---|
id |
integer/string | yes | The ID or URL-encoded path of the group owned by the authenticated user. |
epic_iid |
integer | yes | The internal ID of the epic. |
child_epic_id |
integer | yes | The global ID of the child epic. Internal ID can't be used because they can conflict with epics from other groups. |
curl --header DELETE "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/1/epics/4/epics/5
Example response:
{
"id": 5,
"iid": 38,
"group_id": 1,
"parent_id": null,
"title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",
"description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",
"author": {
"id": 10,
"name": "Lu Mayer",
"username": "kam",
"state": "active",
"avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon",
"web_url": "http://localhost:3001/kam"
},
"start_date": null,
"start_date_is_fixed": false,
"start_date_fixed": null,
"start_date_from_milestones": null,
"end_date": "2018-07-31",
"due_date": "2018-07-31",
"due_date_is_fixed": false,
"due_date_fixed": null,
"due_date_from_milestones": "2018-07-31",
"created_at": "2018-07-17T13:36:22.770Z",
"updated_at": "2018-07-18T12:22:05.239Z",
"labels": []
}