Epics API

原文：https://docs.gitlab.com/ee/api/epics.html

• Epic issues API
• Milestone dates integration
• Epics pagination
• List epics for a group
• Single epic
• New epic
• Update epic
• Delete epic
• Create a todo

Epics API

版本历史

• 在GitLab Ultimate 10.2 中引入.
• 单级史诗在 12.8 中移至 GitLab Premium .

对史诗的每个 API 调用都必须经过身份验证.

如果用户不是组的成员，并且该组是私有的，则对该组的GET请求将导致404状态代码.

如果没有史诗功能，将返回403状态代码.

Epic issues API

史诗问题 API使您可以与史诗相关的问题进行交互.

Milestone dates integration

在 GitLab 11.3 中引入 .

由于可以从相关的发行里程碑动态地获取开始日期和截止日期，因此当用户具有编辑权限时，将显示其他字段. 其中包括两个布尔字段start_date_is_fixed和due_date_is_fixed ，以及四个日期字段start_date_fixed ， start_date_from_inherited_source ， due_date_fixed和due_date_from_inherited_source .

• 不建议使用end_date ，而应使用due_date .
• 不赞成使用start_date_from_milestones ，而建议使用start_date_from_inherited_source
• 不建议使用due_date_from_milestones ，而应使用due_date_from_inherited_source

Epics pagination

默认情况下，因为 API 结果是分页的，所以GET请求一次返回 20 个结果.

阅读有关分页的更多信息.

弃用：不建议使用响应中的reference属性，而推荐使用references . >推出了GitLab 12.6注意： > references.relative相对于正在请求史诗的组. 从史诗组的原始组中提取史诗时， relative格式将与short格式相同，而在请求的交叉组中， relative格式应与full格式相同.

List epics for a group

获取请求的组及其子组的所有史诗.

GET /groups/:id/epics
GET /groups/:id/epics?author_id=5
GET /groups/:id/epics?labels=bug,reproduced
GET /groups/:id/epics?state=opened 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics" 

响应示例：

[  {  "id":  29,  "iid":  4,  "group_id":  7,  "parent_id":  23,  "title":  "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",  "description":  "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",  "state":  "opened",  "confidential":  "false",  "web_url":  "http://localhost:3001/groups/test/-/epics/4",  "reference":  "&4",  "references":  {  "short":  "&4",  "relative":  "&4",  "full":  "test&4"  },  "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,  //deprecated  in  favor  of  start_date_from_inherited_source  "start_date_from_inherited_source":  null,  "end_date":  "2018-07-31",  //deprecated  in  favor  of  due_date  "due_date":  "2018-07-31",  "due_date_is_fixed":  false,  "due_date_fixed":  null,  "due_date_from_milestones":  "2018-07-31",  //deprecated  in  favor  of  start_date_from_inherited_source  "due_date_from_inherited_source":  "2018-07-31",  "created_at":  "2018-07-17T13:36:22.770Z",  "updated_at":  "2018-07-18T12:22:05.239Z",  "closed_at":  "2018-08-18T12:22:05.239Z",  "labels":  [],  "upvotes":  4,  "downvotes":  0  },  {  "id":  50,  "iid":  35,  "group_id":  17,  "parent_id":  19,  "title":  "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.",  "description":  "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",  "state":  "opened",  "web_url":  "http://localhost:3001/groups/test/sample/-/epics/4",  "reference":  "&4",  "references":  {  "short":  "&4",  "relative":  "sample&4",  "full":  "test/sample&4"  },  "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,  //deprecated  in  favor  of  start_date_from_inherited_source  "start_date_from_inherited_source":  null,  "end_date":  "2018-07-31",  //deprecated  in  favor  of  due_date  "due_date":  "2018-07-31",  "due_date_is_fixed":  false,  "due_date_fixed":  null,  "due_date_from_milestones":  "2018-07-31",  //deprecated  in  favor  of  start_date_from_inherited_source  "due_date_from_inherited_source":  "2018-07-31",  "created_at":  "2018-07-17T13:36:22.770Z",  "updated_at":  "2018-07-18T12:22:05.239Z",  "closed_at":  "2018-08-18T12:22:05.239Z",  "labels":  [],  "upvotes":  4,  "downvotes":  0  }  ] 

Single epic

取得史诗

GET /groups/:id/epics/:epic_iid 

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5" 

响应示例：

{  "id":  30,  "iid":  5,  "group_id":  7,  "title":  "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",  "description":  "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",  "state":  "opened",  "web_url":  "http://localhost:3001/groups/test/-/epics/5",  "reference":  "&5",  "references":  {  "short":  "&5",  "relative":  "&5",  "full":  "test&5"  },  "author":{  "id":  7,  "name":  "Pamella Huel",  "username":  "arnita",  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",  "web_url":  "http://localhost:3001/arnita"  },  "start_date":  null,  "start_date_is_fixed":  false,  "start_date_fixed":  null,  "start_date_from_milestones":  null,  //deprecated  in  favor  of  start_date_from_inherited_source  "start_date_from_inherited_source":  null,  "end_date":  "2018-07-31",  //deprecated  in  favor  of  due_date  "due_date":  "2018-07-31",  "due_date_is_fixed":  false,  "due_date_fixed":  null,  "due_date_from_milestones":  "2018-07-31",  //deprecated  in  favor  of  start_date_from_inherited_source  "due_date_from_inherited_source":  "2018-07-31",  "created_at":  "2018-07-17T13:36:22.770Z",  "updated_at":  "2018-07-18T12:22:05.239Z",  "closed_at":  "2018-08-18T12:22:05.239Z",  "labels":  [],  "upvotes":  4,  "downvotes":  0,  "subscribed":  true  } 

New epic

创建一个新的史诗.

注意：从 GitLab 11.3开始，不应再直接分配start_date和end_date ，因为它们现在表示复合值. 您可以改为通过*_is_fixed和*_fixed字段进行配置.

POST /groups/:id/epics 

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics?title=Epic&description=Epic%20description" 

响应示例：

{  "id":  33,  "iid":  6,  "group_id":  7,  "title":  "Epic",  "description":  "Epic description",  "state":  "opened",  "confidential":  "false",  "web_url":  "http://localhost:3001/groups/test/-/epics/6",  "reference":  "&6",  "references":  {  "short":  "&6",  "relative":  "&6",  "full":  "test&6"  },  "author":  {  "name"  :  "Alexandra Bashirian",  "avatar_url"  :  null,  "state"  :  "active",  "web_url"  :  "https://gitlab.example.com/eileen.lowe",  "id"  :  18,  "username"  :  "eileen.lowe"  },  "start_date":  null,  "start_date_is_fixed":  false,  "start_date_fixed":  null,  "start_date_from_milestones":  null,  //deprecated  in  favor  of  start_date_from_inherited_source  "start_date_from_inherited_source":  null,  "end_date":  "2018-07-31",  //deprecated  in  favor  of  due_date  "due_date":  "2018-07-31",  "due_date_is_fixed":  false,  "due_date_fixed":  null,  "due_date_from_milestones":  "2018-07-31",  //deprecated  in  favor  of  start_date_from_inherited_source  "due_date_from_inherited_source":  "2018-07-31",  "created_at":  "2018-07-17T13:36:22.770Z",  "updated_at":  "2018-07-18T12:22:05.239Z",  "closed_at":  "2018-08-18T12:22:05.239Z",  "labels":  [],  "upvotes":  4,  "downvotes":  0  } 

Update epic

更新史诗.

注意：从 GitLab 11.3开始，不应再直接分配start_date和end_date ，因为它们现在表示复合值. 您可以改为通过*_is_fixed和*_fixed字段进行配置.

PUT /groups/:id/epics/:epic_iid 

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5?title=New%20Title" 

响应示例：

{  "id":  33,  "iid":  6,  "group_id":  7,  "title":  "New Title",  "description":  "Epic description",  "state":  "opened",  "confidential":  "false",  "web_url":  "http://localhost:3001/groups/test/-/epics/6",  "reference":  "&6",  "references":  {  "short":  "&6",  "relative":  "&6",  "full":  "test&6"  },  "author":  {  "name"  :  "Alexandra Bashirian",  "avatar_url"  :  null,  "state"  :  "active",  "web_url"  :  "https://gitlab.example.com/eileen.lowe",  "id"  :  18,  "username"  :  "eileen.lowe"  },  "start_date":  null,  "start_date_is_fixed":  false,  "start_date_fixed":  null,  "start_date_from_milestones":  null,  //deprecated  in  favor  of  start_date_from_inherited_source  "start_date_from_inherited_source":  null,  "end_date":  "2018-07-31",  //deprecated  in  favor  of  due_date  "due_date":  "2018-07-31",  "due_date_is_fixed":  false,  "due_date_fixed":  null,  "due_date_from_milestones":  "2018-07-31",  //deprecated  in  favor  of  start_date_from_inherited_source  "due_date_from_inherited_source":  "2018-07-31",  "created_at":  "2018-07-17T13:36:22.770Z",  "updated_at":  "2018-07-18T12:22:05.239Z",  "closed_at":  "2018-08-18T12:22:05.239Z",  "labels":  [],  "upvotes":  4,  "downvotes":  0  } 

Delete epic

删除史诗

DELETE /groups/:id/epics/:epic_iid 

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5" 

Create a todo

在史诗上为当前用户手动创建待办事项. 如果该史诗上已经存在用户的待办事项，则返回状态码304 .

POST /groups/:id/epics/:epic_iid/todo 

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/1/epics/5/todo" 

响应示例：

{  "id":  112,  "group":  {  "id":  1,  "name":  "Gitlab",  "path":  "gitlab",  "kind":  "group",  "full_path":  "base/gitlab",  "parent_id":  null  },  "author":  {  "name":  "Administrator",  "username":  "root",  "id":  1,  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "https://gitlab.example.com/root"  },  "action_name":  "marked",  "target_type":  "epic",  "target":  {  "id":  30,  "iid":  5,  "group_id":  1,  "title":  "Ea cupiditate dolores ut vero consequatur quasi veniam voluptatem et non.",  "description":  "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.",  "author":{  "id":  7,  "name":  "Pamella Huel",  "username":  "arnita",  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon",  "web_url":  "http://localhost:3001/arnita"  },  "web_url":  "http://localhost:3001/groups/test/-/epics/5",  "reference":  "&5",  "references":  {  "short":  "&5",  "relative":  "&5",  "full":  "test&5"  },  "start_date":  null,  "end_date":  null,  "created_at":  "2018-01-21T06:21:13.165Z",  "updated_at":  "2018-01-22T12:41:41.166Z",  "closed_at":  "2018-08-18T12:22:05.239Z"  },  "target_url":  "https://gitlab.example.com/groups/epics/5",  "body":  "Vel voluptas atque dicta mollitia adipisci qui at.",  "state":  "pending",  "created_at":  "2016-07-01T11:09:13.992Z"  }