Backlogの課題追加のAPIで分かりにくい点

はじめに

一括でBacklogの課題（チケット）を作成するために、Backlog APIを使いました。

Backlogの公式リファレンスが少しだけ不親切に感じる箇所があったので、分かりにくかった点を補足します。

（こういう意見みたいなのは、公式にお問い合わせしたほうが良いのでしょうか。）

課題の追加のAPI

こちらが課題の追加のAPIの公式リファレンスです。

• 課題の追加 | Backlog API | Nulab Developers

カスタム属性

カスタム属性の説明が不親切でした。

• そもそもカスタム属性というのが何を指しているのか分からず、察する難易度が高めでした。
• パラメータのキーの説明が customField_{id} とあるだけでしたので、id が何を指していて、値の型が何で、何を入れるのかを察するのが難しかったです。
• ~~必須パラメータであるのに、リファレスンスには必須とは書いていない点も不親切に感じました。~~管理者による設定で必須になっていただけで、本来は必須ではないようでした。すみません。

カスタム属性とは、その名前の通り、管理画面で設定できる課題の属性値のことです。
自分のプロジェクトの設定では、ステータスという名称の属性となっていました。

customField_{id}のidは、カスタム属性のIDを指しています。カスタム属性が設定されたチケットに対して、課題情報の取得のAPIを叩くことで確認できます。表面上は見えないIDです。

keyを動的に変更しないといけないのがトリッキーですね。

後述するように、URLエンコーディングでしかパラメータが渡せないため、ネストしたような構造は渡せません。
苦肉の策で、こういうkeyを動的に指定する微妙な仕様になったのでしょう…

具体例を挙げると、こんな感じです。

GETのレスポンスのカスタム属性の箇所

{
"customFields":[{"id":11223344,
    "fieldTypeId":6,
    "name":"ステータス",
    "value":[{"id":1,
      "name":"未対応",
      "displayOrder":0}]}],
}

POSTのカスタム属性の指定例

customField_11223344=1

ちょっと難しい。。。

URLエンコーディング

リファレンスに書いてあるとおり、Content-Type:application/x-www-form-urlencodedです。

POST であろうが、パラメータはURLに埋め込まないと読んでくれません。

なぜかPOSTはJSONをリクエストボディに入れる先入観があったために、若干ハマりました。リファレンスはよく読みましょう。。。

レスポンスコードは201

これもちゃんとリファレンスには書いてあったのですが、レスポンスコードは201です。
200だったら正常という処理をしていたせいで、これもハマりました…

まとめ

リファレンスはよ〜く読みましょう。

管理者ではない、一般のBacklogユーザにとっては、カスタム属性が何を指すのか察するのは困難でした。
そこの説明はもっと欲しいかなと思いました。