r-labs

redmine.org の "Redmine API":http://www.redmine.org/projects/redmine/wiki/Rest_api の日本語訳です。

{{>toc}}

h1. Redmine REST API

Redmine では REST API が提供されています。 

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

h2. 使用可能なデータの一覧

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

|_. データ                        |_.ステータス |_.注意点  |_.Redmine バージョン|

|[[Rest_Issues|チケット]]         | Beta  | 荒削りの段階でまだバグが残っています  | 1.0 |

|[[Rest_Projects|プロジェクト]]   | Beta  | 荒削りの段階でまだバグが残っています  | 1.0 |

|[[Rest_Users|ユーザー]]          | Beta  | | 1.1 |

|[[Rest_TimeEntries|作業時間の記録]] | Beta  | | 1.1 |

|[[Rest_News|News]]               | Prototype | @index@ だけの試験的な実装です | 1.1 |

|[[Rest_IssueRelations|Issue Relations]] | Alpha | | 1.3 |

|[[Rest_Versions|Versions]]       | Alpha | | 1.3 |

|[[Rest_Queries|Queries]]         | Alpha | | 1.3 |

|[[Rest_Attachments|Attachments]] | Alpha | | 1.3 |

ステータスの凡例 :

* Stable - 仕様機能は完成されていて、今後の大きな変更は予定されていません。

* Beta   - まだバグが残っているか、いくつかの細かな機能が実装されていません。

* Alpha  - 主要な機能は出来てますが、まだ API 使用者からのフィードバッグを必要としています。

* Prototype - 試験的な運用のためにざっと実装されただけで、今後大きな変更が加わる可能性があります。 *本格的に使用するのはお勧めできません*

* Planned - 将来のバージョンで予定されているもので、いつになるかは開発参加者によって変わってきます。

h2. 各データ共通

h3. ユーザー認証

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

API 型式での認証を可能にするためには 

_管理_ → _設定_ → _認証_ の順で設定ページを表示した後、

*[REST による Web サービスを有効にする]* にチェックを入れます。

!auth_settings.png!

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

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

* "key" パラメーター

* 基本的な HTTP 認証でのランダムなパスワードのユーザー

* "X-Redmine-API-Key" の HTTP ヘッダ (Redmine 1.1.0 で追加)

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

!api_key.png!

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

データリストを取得する GET リクエスト(@/issues.xml@, @/users.xml@ など)では、通常データベース内の利用可能な全てのデータが一度に返ってくるわけではありません。

Redmine のバージョン 1.1.0 以降ではデータを要求する各リクエストに対して次のパラメータが共通して使用できるようになっています。

* @offset@: データ取得の開始位置

* @limit@: 取得するデータ数 (デフォルトは 25 で、 最大が 100)

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

+例+:

<pre>

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

=> 前のリクエストと同じです

</pre>

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

+例(XML)+:

<pre>

GET /issues.xml

</pre><pre><code class="xml">

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

  ...

</issues>

</code></pre>

+例(JSON)+:

<pre>

GET /issues.json

</pre><pre><code class="json">

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

</code></pre>

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

<pre>

GET /issues.xml?nometa=1

</pre><pre><code class="xml">

<issues type="array">

  ...

</issues>

</code></pre>

h3. 関連データの取得

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

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

<pre>

GET /issues/296.xml?include=journals

</pre><pre><code class="xml">

<issue>

  <id>296</id>

  ...

  <journals type="array">

  ...

  </journals>

</issue>

</code></pre>

複数の関連データを得たい場合にはカンマで区切って指定します。

+例+:

<pre>

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

</pre><pre><code class="xml">

<issue>

  <id>296</id>

  ...

  <journals type="array">

  ...

  </journals>

  <changesets type="array">

  ...

  </changesets>

</issue>

</code></pre>

h3. カスタムフィールドがある場合

Redmine のほとんどのデータではカスタムフィールドを使用することが出来ます。

このカスタムフィールドの値は @custom_fields@ 要素に記述されています。

+例(XML)+:

<pre>

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

</pre><pre><code class="xml">

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

</code></pre>

+例(JSON)+:

<pre>

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

</pre><pre><code class="json">

{"issue":

  {

    "id":8471,

    ...

    "custom_fields":

      [

        {"value":"1.0.1","name":"Affected version","id":1},

        {"value":"Fixed","name":"Resolution","id":2}

      ]

  }

}

</code></pre>

データの作成や更新時にカスタムフィールドの値も一緒に設定や変更をしたい場合には、どちらも同じ文法で記述できます(カスタムフィールドの名前を必要としない場合を除く)。

+例(XML)+:

<pre>

PUT /issues/296.xml

</pre><pre><code class="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>

</code></pre>

*注意*: @custom_fields@ の XML タグにある @type="array"@ 属性は必ず付ける必要があります。

+例(JSON)+:

<pre>

PUT /issues/296.json

</pre><pre><code class="json">

{"issue":

  {

    "subject":"Updating custom fields of an issue",

    ...

    "custom_fields":

      [

        {"value":"1.0.2","id":1},

        {"value":"Invalid","id":2}

      ]

  }

}

</code></pre>

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

* [[Rest_api_with_ruby|Ruby]]

* [[Rest_api_with_php|PHP]]

* [[Rest_api_with_python|Python]]

* [[Rest_api_with_java|Java]]

* [[Rest_api_with_curl|cURL]]

* "Drupal Redmine API module, 2.x branch (currently not stable)":http://drupal.org/project/redmine

* [[Rest_api_with_csharp|.NET]]

* [[Rest_api_with_delphi|Delphi]]