redmine.org の Redmine API の日本語訳です。

• Table of contents
• Redmine REST API
  • 使用可能なデータの一覧
  • 各データ共通
    • ユーザー認証
    • データリストの取得とページ割り
    • 関連データの取得
    • カスタムフィールドがある場合
  • 言語やツールごとの API の使用法

Redmine REST API¶

Redmine では REST API が提供されています。
この API を使って Redmine 上のデータにアクセスすることができ、 CRUD と呼ばれる 作成、読み取り、更新、削除 といった基本的な操作を行うことが出来ます。

使用可能なデータの一覧¶

API が用意されているデータには以下の表のものがあります。

データ	ステータス	注意点	Redmine バージョン
チケット	Beta	荒削りの段階でまだバグが残っています	1.0
プロジェクト	Beta	荒削りの段階でまだバグが残っています	1.0
ユーザー	Beta		1.1
作業時間の記録	Beta		1.1
News	Prototype	index だけの試験的な実装です	1.1
Issue Relations	Alpha		1.3
Versions	Alpha		1.3
Queries	Alpha		1.3
Attachments	Alpha		1.3

ステータスの凡例 :

• Stable - 仕様機能は完成されていて、今後の大きな変更は予定されていません。
• Beta - まだバグが残っているか、いくつかの細かな機能が実装されていません。
• Alpha - 主要な機能は出来てますが、まだ API 使用者からのフィードバッグを必要としています。
• Prototype - 試験的な運用のためにざっと実装されただけで、今後大きな変更が加わる可能性があります。 本格的に使用するのはお勧めできません
• Planned - 将来のバージョンで予定されているもので、いつになるかは開発参加者によって変わってきます。

各データ共通¶

ユーザー認証¶

ほとんどの場合、 API では認証を必要とします。

API 型式での認証を可能にするためには
管理 → 設定 → 認証 の順で設定ページを表示した後、
[REST による Web サービスを有効にする] にチェックを入れます。

そうすると普段のログイン名とパスワードを使用した HTTP 認証方法の他に API キーを使った認証が利用できるようになります。 API キーを使うとスクリプト中にパスワードの記述を避けることが簡単に出来ます。

次の方法で各リクエストに対して API キーを付けることが可能です。

• "key" パラメーター
• 基本的な HTTP 認証でのランダムなパスワードのユーザー
• "X-Redmine-API-Key" の HTTP ヘッダ (Redmine 1.1.0 で追加)

自分の API キーを知りたい場合には、ログイン後、 [個人設定](/my/account)ページを開き、ページの右側(デフォルトテーマの場合)を見て下さい。

データリストの取得とページ割り¶

データリストを取得する GET リクエスト(/issues.xml, /users.xml など)では、通常データベース内の利用可能な全てのデータが一度に返ってくるわけではありません。
Redmine のバージョン 1.1.0 以降ではデータを要求する各リクエストに対して次のパラメータが共通して使用できるようになっています。

• offset: データ取得の開始位置
• limit: 取得するデータ数 (デフォルトは 25 で、 最大が 100)

offset の代わりに、 limit と併用して page パラメーターを使用することも出来ます。

例:

GET /issues.xml
=> 最初の 25 チケットが返ってきます

GET /issues.xml?limit=100
=> 最初の 100 チケットが返ってきます

GET /issues.xml?offset=30&limit=10
=> 30 番目からの 10 チケットが返ってきます

GET /issues.xml?page=3&limit=10
=> 前のリクエストと同じです

データ一覧の GET リクエストから返ってくるレスポンス情報の中には利用可能な全データの要素数や使用した offset/limit の値が含まれています。
例(XML):

GET /issues.xml

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

例(JSON):

GET /issues.json

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

注意: トップレベルにある total_count, limit, offset といった属性に対して、使用している REST クライアントが対応していない場合には nometa パラメーターか X-Redmine-Nometa の HTTP ヘッダのどちらかを設定すれば、属性を除いた応答が返ってきます。

GET /issues.xml?nometa=1

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

関連データの取得¶

バージョン 1.1.0 以降、関連データを含んだ検索結果を得たい場合には、 URL に include パラメーターを付けて、明示的に指定する必要があります。

例: チケット履歴(journals)の記述を取得

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}
      ]
  }
}

言語やツールごとの API の使用法¶

• Ruby
• PHP
• Python
• Java
• cURL
• Drupal Redmine API module, 2.x branch
• .NET
• Delphi