JIRA REST API 使用说明

API 结构

JIRA的REST API通过URI路径提供对资源（数据实体）的访问。 JIRA REST API使用JSON作为其通信格式，以及标准的HTTP方法，如GET，PUT，POST和DELETE。 JIRA的REST API资源的URI具有以下结构：

http://host:port/context/rest/api-name/api-version/resource-name

CODE

host:port/context : JIRA的访问URL
rest : 固定的rest
api-name 有两个值
- auth：对于与认证相关的操作
- api: 其他api操作，通常情况下都是用的 api
api-version : 目前的版本是2, 也可以用latest

认证

JIRA中API的认证方式有两种

OAuth 1.0
basic authentication

OAuh 提供标准的3-legged OAuth (3LO) 认证方式，需要调用API的client支持OAuth，并在JIRA 上设置Application link，详细使用和设置请参见官方文档https://developer.atlassian.com/server/jira/platform/oauth/

Basic Authentication 即基础的基于用户名和密码的认证，虽然安全性较差，但使用简单方便，通常用作调试和简单的API调用使用

使用 Basic Authentication 把用户名和密码在http的请求头中通过base64的编码后进行传输

生成一个字符串 username:password ， username和password之间用 : 号分隔
将 username:password 使用 base64进行编码
生成一个 Authorization header, 内容为 "Basic 编码后的内容" ，比如 “fred:fred” base64 编码后为 “ZnJlZDpmcmVk” ，那么API调用的请求构建为

curl -D- -X GET -H "Authorization: Basic ZnJlZDpmcmVk" -H "Content-Type: application/json" "http://localhost:8080/rest/api/2/issue/QA-31"

CODE

使用API的其他事项

Expansion 扩展

为了简化API响应，JIRA REST API使用资源扩展。这意味着API只会在明确请求时才返回资源的一部分，有些内容需要使用expland来获取

可以使用expand查询参数来指定要扩展的实体的逗号分隔列表，并按名称标识它们中的每一个。例如，将？expand = names，renderedFields附加到问题的URI请求在响应中包含翻译的字段名称和HTML呈现的字段值。下面的示例展开问题JRA-9的名称和renderedFields字段

https://jira.atlassian.com/rest/api/latest/issue/JRA-9?expand=names,renderedFields

CODE

如果要查看哪些内容是expand的，可以查看parent object的expand属性，比如要查看issue的expand属性，可以从查看issue的response的相应值中看到

"issues": [
        {
            "expand": "operations,versionedRepresentations,editmeta,changelog,renderedFields",

CODE

分页

JIRA使用分页来限制返回潜在大量资源响应大小。对分页API的请求将导致将值数组封装在带有一些分页元数据的JSON对象中，例如：

{
    "startAt" : 0,
    "maxResults" : 10,
    "total": 200,
    "values": [
        { /* result 0 */ },
        { /* result 1 */ },
        { /* result 2 */ }
    ]
}

CODE

startAt: 结果页面的起始位置
maxResults: 每页返回的最大数目
total: 要求返回的项目总数
isLastPage: 指示返回的当前页面是否是结果的最后一页

排序

有些资源支持按特定字段排序。这由orderBy查询参数提供。

排序可以是升序或降序。要指定排序的类型，请分别使用“+”或“ - ”符号进行升序或降序。默认情况下，排序是升序。

例如，?orderBy=+name 将按名称以升序排列结果。

Self 链接

许多字段都有一个“self”，使用self可以直接访问该资源，获取资源的详细信息，如

"reporter": {
    "self": "http://jira.atlassian.com/rest/api/2/user?username=admin",
    "name": "admin",
    "emailAddress": "admin@example.com",
    "displayName": "Administrator",
    "active": true
},

CODE

字段的输入格式

Summary 概要

"summary": "issue名称描述"

CODE

Description 描述

"description": "This is an example description with multiples lines of text\n separated by\n line feeds"

CODE

Components 模块

"components" : [ { "name": "Active Directory"} , { "name": "Network Switch" } ]

CODE

Due date 到期日

"duedate" : "2015-11-18"

CODE

Labels 标签

"labels" : ["examplelabelnumber1", "examplelabelnumber2"]

CODE

Checkbox custom field 复选框自定义字段

"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]

CODE

或者使用 id

"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}]

CODE

Date picker custom field 日期选择器自定义字段

时间格式 YYYY-MM-DD

"customfield_11441" : "2015-11-18"

CODE

Date time picker custom field 日期时间选择器自定义字段

ISO 8601 YYYY-MM-DDThh:mm:ss.sTZD 格式

"customfield_11442" : "2015-11-18T14:39:00.000+1100"

CODE

Labels custom field: 标签自定义字段

"customfield_11443" : [ "rest_label1", "rest_label2" ]

CODE

`Number custom field 数值型自定义字段`

"customfield_11444" : 123

CODE

Radio button custom field 单选按钮自定字段

"customfield_11445" : { "value": "option2" }

CODE

或者使用 ID

"customfield_11445" : { "id": 10112 }

CODE

Cascading select custom field 级联列表自定字段

"customfield_11447" : { "value": "parent_option1", "child": { "value" : "p1_child1"} }

CODE

或者使用id

"customfield_11447" : { "id": 10112, "child": { "id" : 10115 } }

CODE

Multi-select custom field 多选自定义字段

"customfield_11448" : [ { "value": "option1" }, { "value": "option2" } ]

CODE

或者使用id

"customfield_11448" : [ { "id": 10112 }, { "id": 10115 } ]

CODE

Single-select custom field 单选自定义字段

"customfield_11449" : { "value": "option3" }

CODE

或者使用id

"customfield_11449" : { "id": 10112 }

CODE

Multi-line text custom field 多行文本框自定义字段

"customfield_11450": "An example of multiples lines of text\n separated by\n line feeds"

CODE

Text custom field 文本框自定义字段

"customfield_11450": "An example of a single line of text"

CODE

URL custom field URL链接自定字段

"customfield_11452" : "http://www.atlassian.com"

CODE

Single-user picker custom field 单选用户自定义字段

"customfield_11453" : { "name":"tommytomtomahawk" }

CODE

Multi-user picker custom field 多选用户自定义字段

"customfield_11458" : [ { "name":"inigomontoya" }, { "name":"tommytomtomahawk" }]

CODE

注：自定字段 customfield_xxxx 的数字的值需要根据您系统中具体的字段的编号填入

API使用的一个例子

API 的使用举例将在下一章节中专门讲述，本页提供了一个简单的例子帮助开始使用API

该示例向您展示了如何使用JIRA REST API创建问题。示例代码使用curl发出请求，但您可以使用任何您喜欢的工具。

注意：

输入文件由'--data @filename'语法表示。数据使用JSON格式，存放在filename的文件中。
确保请求中的内容类型设置为'application/json'，如示例中所示。
将JSON发布到您的JIRA服务器。在这个例子中，服务器是http://localhost:8080/jira/rest/api/2/issue /。
该示例使用基本身份验证，用户名为admin，密码为admin

使用API创建一个issue

1. 创建包含POST数据的数据文件。在这个例子中，我们假定文件名为data.txt。将下面显示的JSON添加到文件中。

在这个数据中，project ID是10000，我们的例子中的问题类型是3，它代表一项任务。您应该在实例中选择一个项目的ID，并选择您喜欢的任何类型的问题。

json数据内容如下

{
    "fields": {
       "project":
       {
          "id": "10000"
       },
       "summary": "No REST for the Wicked.",
       "description": "Creating of an issue using ids for projects and issue types using the REST API",
       "issuetype": {
          "id": "3"
       }
   }
}

CODE

另外，project 也可以使用 key 来标识，比如 key : TEST

issue type 也可以使用 name 来标识，比如 name : task

2. 通过curl 命令（也可以使用其他工具，如postman）生成一个POST 请求

curl -u admin:admin -X POST --data @data.txt -H "Content-Type: application/json" http://localhost:8080/jira/rest/api/2/issue/

CODE

3. 发出POST请求后将受到一个issue 创建成功的相应

{
   "id":"10009",
   "key":"TEST-10",
    "self":"http://localhost:8080/jira/rest/api/2/issue/10009"
}

CODE

issue 就创建成功过了，返回的内容包括issue的ID，Key以及链接