backlogAPIの特に課題の追加、編集でハマる所

3360 ワード
Backlog backlogapi api api テキストリンク

backlogAPIのドキュメント、分かりづらくない？

ディスってすいません。なんかやろうとすると、いつも細かいところで躓く。
明文化されていないことが多くない？？
あとエラーの返却が全て400のBad Requestなのも萎える。

URLについての注意事項

APIキー

GET、POST、PATCH、DELETE全てにおいて、GETパラメータでapikey=XXX が必要。
POST、PATCH、DELETEの場合もそうなので注意。

URLの正確性

URL全般、URLの最後に"/" がつくとエラーになるので注意。
例）
課題の追加API(POST）

NG： https://XXX.backlog.jp/api/v2/issues/?apiKey=XXXX
OK： https://XXX.backlog.jp/api/v2/issues?apiKey=XXXX
                                      ^^^←ここ

課題の追加、編集のハマり点

全般

ドキュメントに書かれているリクエストパラメータ以外がパラメータに含まれると400 BadRequestエラー。

課題の追加API（POST)

URL

/api/v2/issues
※もちろんパラメータにapiKey=XXX が必要です。

必須項目

パラメーター名 型 内容
projectId (必須) 数値 課題を登録するプロジェクトのID
summary (必須) 文字列 課題の件名
issueTypeId (必須) 数値 課題の種別のID
priorityId (必須) 数値 課題の優先度のID

priorityIdは、全バックログで共通の値"3"（中）が使えるのでまだいい。
issueTypeIdは、各プロジェクトごとに違うので気合で探す必要がある。
しかも、課題一覧の取得APIでissueTypeId、priorityIdは返却されない。
issueType.id、priority.idという形で返却される。INとOUTしっかりしてほしい。
というかそもそもそれら必須である意味あるか？？

課題情報の更新API（PATCH)

URL

/api/v2/issues/:issueIdOrKey
※もちろんパラメータにapiKey=XXX が必要です。

この:issueIdOrKeyが厄介。ドキュメントにはこう書かれています。

URLパラメーター

パラメーター名 型 内容
issueIdOrKey 文字列 課題のID または 課題キー

まず、こういう書き方するのならapiKeyのことをgetパラメータで必須って書いてほしいよね。
このドキュメントで「課題のID」、「課題キー」という言葉は多分出てきていないんですよね。
課題一覧の取得で取れるは取れるのですが、そちらでもレスポンス情報の解説が無いから
どれがIDでどれがキーかはひと目では分からない。
レスポンスのidが、課題のID、issueKeyが、課題キーのようです。

課題情報の更新API、最大の注意点

なんと、「更新する情報が無かった場合はエラー：400 BadRequestを返却する」!!!!!!!
普通正常終了じゃない？

まとめ

みんなもAPIを作る時はドキュメントをしっかり書こうね。
この本がとてもタメになりました。
この想い、バックログの中の人に届けー