简介

Jira的REST APIs 被用于jira服务器应用之间的远程交互，jira软件和service desk应用的REST APIs拥有其应用特定的特征，例如sprint或者消费者请求。

授权与认证

授权与认证可以采用以下两种方式之一：

URL结构

REST API可以让我们通过URL路径来访问jira应用的资源，使用REST API，应用需要创建HTTP的请求并对响应进行解析。

JIRA REST API使用JSON作为它的通信格式并且采用了例如GET、PUT、POST、和DELETE等HTTP方法。JIRA的URLs通常为以下的结构：

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

使用REST APIs

下面的主题是关于如何使用Jira REST APIs，以及如何使用它们进行交互。

Expansion

为了简化API的响应，Jira REST API使用资源扩展。这意味着API将会返回明确请求的资源的那部分。这会帮助你避免在请求的资源过多或过少时发生的问题。

你可以使用expand查询参数来指定一个你想要展开的实体的逗号分隔的列表，并根据名称来标识它们。

下面的例子展开了issue JRA-9的name和renderedFields：

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

返回的信息如下：

{
    "expand": "widgets",
    "self": "http://jira.atlassian.com/rest/api/resource/KEY-1",
    "widgets": { "widgets": [], "size": 5 }
}

Pagination

Jira使用分页来限制返回资源的尺寸。一个分页API的请求将会返回如下的结构：

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

startAt：返回列表中该页起始的元素
maxResults：每页返回的项目的个数
total：返回项目的总数
isLastPage：当前页是否为最后一页

客户端可以使用startAt、maxResults和total来从返回结果中获取想要得到的数据。

Ordering

有些资源支持对特定的域进行排序，这个功能由一个orderBy查询参数提供。

排序支持升序和降序。可用“+”和“-”来分别指定升序和降序。默认的，排序是升序的。例如，?orderBy=+name。

Self links

许多域有一个自链接来让你访问该资源的规范位置。例如：

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

创建一个GET请求给自链接有时候能够提供给你过关于这个域的额外的信息。

特殊请求和响应的报头

X-AUSERNAME 包含授权用户或者匿名者的用户名的响应报头
X-Atlassian-Token 接受复数部分或表单数据的方法将只会执行拥有X-Atlassian-Token：no-check报头的请求

错误响应

多数资源会然会一个带状态码的响应报文，通常，返回的实体的json如下所示：

{
    "id": "https://docs.atlassian.com/jira/REST/schema/error-collection#",
    "title": "Error Collection",
    "type": "object",
    "properties": {
        "errorMessages": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "errors": {
            "type": "object",
            "patternProperties": {
                ".+": {
                    "type": "string"
                }
            },
            "additionalProperties": false
        },
        "status": {
            "type": "integer"
        }
    },
    "additionalProperties": false
}

域输入格式

Summary

一个单行文本的系统域

"summary": "This is an example summary"

Description

一个多行文本的系统域

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

Components

一个有多个键值对构成的系统域：

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

Due date

一个以“YYYY-MM-DD”格式保存日期的系统域：

"duedate" : "2015-11-18"

Labels

一个有字符串列表构成的系统域：

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

Checkbox custom Field

一个自定义的域，允许你从一个已定义的数值列表中选择复数值。你能够根据value或ID来找到它们。

"customfield_11440" : [{ "value" : "option1"}, {"value" : "option2"}]
"customfield_11440" : [{ "id" : 10112}, {"id" : 10115}]

Date picker custom field

一个“YYYY-MM-DD”格式的日期的自定义域：

"customfield_11441" : "2015-11-18"

Data time picker custom field:

一个“ ISO 8601 YYYY-MM-DDThh:mm:ss.sTZD ”格式的时间的自定义域：

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

Labels custom field

一个字符串列表构成的自定义域：

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

Number custom field

一个包含一个数字的自定义域：

"customfield_11444" : 123

…其它域说明详见官网

JIRA-REST APIs 简介