操作

Redmine API¶

Redmine通过REST API公开其部分数据。此API提供了对以下资源的访问和基本的CRUD操作（创建、更新、删除）。API支持XML和JSON格式。

API描述¶

资源	状态	备注	可用性
问题	稳定		1.0
项目	稳定		1.0
项目成员	alpha		1.4
用户	稳定		1.1
时间条目	稳定		1.1
新闻	原型	仅为`index`的实现原型	1.1
问题关系	alpha		1.3
版本	alpha		1.3
Wiki页面	alpha		2.2
查询	alpha		1.3
附件	beta	通过API添加的1.4版中的附件添加	1.3
问题状态	alpha	提供所有状态列表	1.3
跟踪器	alpha	提供所有跟踪器列表	1.3
枚举	alpha	提供问题优先级和时间跟踪活动的列表	2.2
问题类别	alpha		1.3
角色	alpha		1.4
组	alpha		2.1
自定义字段	alpha		2.4
搜索	alpha		3.3
文件	alpha		3.4
我的账户	alpha		4.1
日志	alpha		5.0

状态图例

稳定 - 功能完整，没有计划进行重大更改
beta - 可用于集成，可能存在一些错误或缺少一些小功能
alpha - 完成了主要功能，需要API用户和集成商的反馈
原型 - 非常粗糙的实现，可能在中版本期间进行重大更改。**不建议用于集成**
计划 - 计划在未来版本中，取决于开发者的可用性

您可以查看每个版本的API更改列表。

通用主题¶

在POST/PUT请求中指定`Content-Type`¶

在创建或更新远程元素时，即使远程URL相应地后缀（例如，POST ../issues.json），请求的Content-Type也**必须**指定。

对于JSON内容，必须设置为Content-Type: application/json。
对于XML内容，设置为Content-Type: application/xml。

身份验证¶

大多数情况下，API 需要身份验证。要启用 API 风格的身份验证，您需要在“管理”->“设置”->“API”中检查“启用 REST API”。然后，可以通过两种不同的方式进行身份验证

使用您的常规登录名/密码通过 HTTP Basic 验证。
使用您的 API 密钥，这是一种避免将密码放入脚本中的便捷方法。API 密钥可以通过以下方式之一附加到每个请求
- 作为“key”参数传递
- 通过 HTTP Basic 验证以随机密码作为用户名传递
- 作为“X-Redmine-API-Key” HTTP 头部传递（从 Redmine 1.1.0 版本开始）

您可以在登录后访问您的账户页面（/my/account），在默认布局的右侧面板中找到您的 API 密钥。

用户模拟¶

从 Redmine 2.2.0 版本开始，您可以通过设置 API 请求的 X-Redmine-Switch-User 头部来通过 REST API 模拟用户。它必须设置为用户登录名（例如：X-Redmine-Switch-User: jsmith）。这仅在使用管理员账户的 API 时有效，使用常规用户账户时将忽略此头部。

如果通过 X-Redmine-Switch-User 头部指定的登录名不存在或未激活，您将收到 412 错误响应。

集合资源和分页¶

对集合资源（例如 /issues.xml，/users.xml）的 GET 请求的响应通常不会返回数据库中所有可用的对象。Redmine 从 1.1.0 版本引入了一种通用的方法来查询此类资源，使用以下参数

offset：要检索的第一个对象的偏移量
limit：响应中要包含的项目数（默认为 25，最大为 100）

示例

GET /issues.xml
=> returns the 25 first issues

GET /issues.xml?limit=100
=> returns the 100 first issues

GET /issues.xml?offset=30&limit=10
=> returns 10 issues from the 30th

对集合资源的 GET 请求的响应提供有关 Redmine 中可用的总对象数以及用于响应的偏移量/限制的信息。示例

GET /issues.xml

<issues type="array" total_count="2595" limit="25" offset="0">
  ...
</issues>

GET /issues.json

{ "issues":[...], "total_count":2595, "limit":25, "offset":0 }

注意：如果您使用不支持此类顶级属性（total_count，limit，offset）的 REST 客户端，则可以设置 nometa 参数或 X-Redmine-Nometa HTTP 头部为 1，以获取不包含它们的响应。示例

GET /issues.xml?nometa=1

<issues type="array">
  ...
</issues>

检索关联数据¶

从 1.1.0 版本开始，您必须通过将 include 参数追加到查询 URL 中显式指定您想要包含在查询结果中的关联

示例

检索包含描述的 issue 日志

GET /issues/296.xml?include=journals

<issue>
  <id>296</id>
  ...
  <journals type="array">
  ...
  </journals>
</issue>

您还可以使用以逗号分隔的项目列表加载多个关联。

示例

GET /issues/296.xml?include=journals,changesets

<issue>
  <id>296</id>
  ...
  <journals type="array">
  ...
  </journals>
  <changesets type="array">
  ...
  </changesets>
</issue>

与自定义字段一起工作¶

Redmine 中的大多数对象都支持自定义字段。它们的值可以在 custom_fields 属性中找到。

XML 示例

GET /issues/296.xml      # an issue with 2 custom fields

<issue>
  <id>296</id>
  ...
  <custom_fields type="array">
    <custom_field name="Affected version" id="1">
      <value>1.0.1</value>
    </custom_field>
    <custom_field name="Resolution" id="2">
      <value>Fixed</value>
    </custom_field>
  </custom_fields>
</issue>

JSON 示例

GET /issues/296.json      # an issue with 2 custom fields

{"issue":
  {
    "id":8471,
    ...
    "custom_fields":
      [
        {"value":"1.0.1","name":"Affected version","id":1},
        {"value":"Fixed","name":"Resolution","id":2}
      ]
  }
}

您还可以使用相同的语法设置/更改自定义字段的值（除了不需要自定义字段名称之外）来创建/更新对象。

XML 示例

PUT /issues/296.xml

<issue>
  <subject>Updating custom fields of an issue</subject>
  ...
  <custom_fields type="array">
    <custom_field id="1">
      <value>1.0.2</value>
    </custom_field>
    <custom_field id="2">
      <value>Invalid</value>
    </custom_field>
  </custom_fields>
</issue>

注意：custom_fields XML 标记上的 type="array" 属性是严格必需的。

JSON 示例

PUT /issues/296.json

{"issue":
  {
    "subject":"Updating custom fields of an issue",
    ...
    "custom_fields":
      [
        {"value":"1.0.2","id":1},
        {"value":"Invalid","id":2}
      ]
  }
}

附加文件¶

通过 REST API 添加附件的支持是在 Redmine 1.4.0 版本中添加的。

首先，您需要使用 POST 请求将每个文件上传到 /uploads.xml（或 /uploads.json）。请求正文应该是您想要附加的文件内容，并且必须将 Content-Type 头部设置为 application/octet-stream（否则您将收到 406 Not Acceptable 响应）。如果上传成功，您将收到包含上传文件令牌的 201 响应。

然后您可以使用此令牌将上传的文件附加到新问题或现有问题。

XML 示例

首先，上传您的文件

POST /uploads.xml?filename=image.png
Content-Type: application/octet-stream
...
(request body is the file content)

# 201 response
<upload>
  <token>7167.ed1ccdb093229ca1bd0b043618d88743</token>
</upload>

然后使用上传令牌创建问题

POST /issues.xml
<issue>
  <project_id>1</project_id>
  <subject>Creating an issue with a uploaded file</subject>
  <uploads type="array">
    <upload>
      <token>7167.ed1ccdb093229ca1bd0b043618d88743</token>
      <filename>image.png</filename>
      <description>An optional description here</description>
      <content_type>image/png</content_type>
    </upload>
  </uploads>
</issue>

如果您尝试上传超过允许最大大小的文件，则会收到422响应

POST /uploads.xml?filename=image.png
Content-Type: application/octet-stream
...
(request body larger than the maximum size allowed)

# 422 response
<errors>
  <error>This file cannot be uploaded because it exceeds the maximum allowed file size (1024000)</error>
</errors>

JSON 示例

首先，上传您的文件

POST /uploads.json?filename=image.png
Content-Type: application/octet-stream
...
(request body is the file content)

# 201 response
{"upload":{"token":"7167.ed1ccdb093229ca1bd0b043618d88743"}}

然后使用上传令牌创建问题

POST /issues.json
{
  "issue": {
    "project_id": "1",
    "subject": "Creating an issue with a uploaded file",
    "uploads": [
      {"token": "7167.ed1ccdb093229ca1bd0b043618d88743", "filename": "image.png", "content_type": "image/png"}
    ]
  }
}

您还可以上传多个文件（通过向/uploads.json发送多个POST请求），然后创建带有多个附件的问题

POST /issues.json
{
  "issue": {
    "project_id": "1",
    "subject": "Creating an issue with a uploaded file",
    "uploads": [
      {"token": "7167.ed1ccdb093229ca1bd0b043618d88743", "filename": "image1.png", "content_type": "image/png"},
      {"token": "7168.d595398bbb104ed3bba0eed666785cc6", "filename": "image2.png", "content_type": "image/png"}
    ]
  }
}

验证错误¶

当尝试创建或更新具有无效或缺失属性参数的对象时，您将收到422 Unprocessable Entity响应。这意味着无法创建或更新该对象。在这种情况下，响应体包含相应的错误消息

XML 示例:

# Request with invalid or missing attributes
POST /users.xml
<user>
  <login>john</login>
  <lastname>Smith</lastname>
  <mail>john</mail>
</uer>

# 422 response with the error messages in its body
<errors type="array">
  <error>First name can't be blank</error>
  <error>Email is invalid</error>
</errors>

JSON 示例:

# Request with invalid or missing attributes
POST /users.json
{
  "user":{
    "login":"john",
    "lastname":"Smith",
    "mail":"john" 
  }
}

# 422 response with the error messages in its body
{
  "errors":[
    "First name can't be blank",
    "Email is invalid" 
  ]
}

JSONP支持¶

Redmine 2.1.0+ API支持JSONP，以便从不同域名（例如，使用JQuery）的红mine服务器请求数据。回调可以通过callback或jsonp参数传递。截至Redmine 2.3.0，JSONP支持是可选的，默认情况下是禁用的，您可以通过在“管理”->“设置”->“API”中选中“启用JSONP支持”来启用它。

示例

GET /issues.json?callback=myHandler

myHandler({"issues":[ ... ]})

各种语言/工具中的API使用¶

API变更历史¶

本节列出了可能破坏向后兼容性的现有API功能的更改。API的新功能列在API描述中。

2012-01-29: 多选自定义字段（《r8721》，《1.4.0》）¶

现在Redmine支持具有多个值的自定义字段，并且可以在API响应中找到这些字段。这些自定义字段具有multiple=true属性，其value属性是数组。

示例

GET /issues/296.json

{"issue":
  {
    "id":8471,
    ...
    "custom_fields":
      [
        {"value":["1.0.1","1.0.2"],"multiple":true,"name":"Affected version","id":1},
        {"value":"Fixed","name":"Resolution","id":2}
      ]
  }
}

文件（0）

最后更新于Go MAEDA 2年前 · 102次修订锁定

项目

通用

个人资料

Redmine

最新版本¶

资源¶

Wiki

Redmine API¶

API描述¶

通用主题¶

在POST/PUT请求中指定`Content-Type`¶

身份验证¶

用户模拟¶

集合资源和分页¶

检索关联数据¶

与自定义字段一起工作¶

附加文件¶

验证错误¶

JSONP支持¶

各种语言/工具中的API使用¶

API变更历史¶

2012-01-29: 多选自定义字段（《r8721》，《1.4.0》）¶

项目

通用

个人资料

Redmine

最新版本¶

资源¶

Wiki

Redmine API¶

API描述¶

通用主题¶

在POST/PUT请求中指定Content-Type¶

身份验证¶

用户模拟¶

集合资源和分页¶

检索关联数据¶

与自定义字段一起工作¶

附加文件¶

验证错误¶

JSONP支持¶

各种语言/工具中的API使用¶

API变更历史¶

2012-01-29: 多选自定义字段（《r8721》，《1.4.0》）¶

在POST/PUT请求中指定`Content-Type`¶