【初心者向け】Jira REST APIの公式ドキュメントの見方をやさしく解説！

はじめに

Jiraを業務で使っていると、「もっと自動化できたら便利なのに…」と思うことはありませんか？

そんなときに役立つのが「Jira REST API」です。APIを使えば、Jiraの操作を自動化できるようになります。

便利なJiraのAPIはたくさんありますが、「どのように使えばいいかわからない…」「公式ドキュメントって英語ばかりでむずかしそう…」という人も多いのではないでしょうか？

この記事では、JiraのAPIを使いこなすために、公式ドキュメントのどこを見ればよいかをやさしく解説します。

Jira REST APIの公式ドキュメントとは？

公式ドキュメントは、Jiraの各機能をAPIで操作するための説明書で、次のようなことがまとめられています。

わかること	内容例
どんな操作ができるのか	課題の取得・作成・更新・削除など
どこにアクセスすればよいか	どんなURLにリクエストを送るか
何を送ればよいか	リクエストに必要な情報（タイトルや担当者など）
何が返ってくるか	課題の詳細、ステータス、コメントなどのJSONデータ

公式ドキュメントの基本構成を見てみよう

まずは、Jira REST APIの公式ドキュメントのページ構成をざっくり理解しましょう。APIごとのページは、おおよそ次のような構成になっています。

APIにはどんなものがある？

公式ドキュメントの左側メニューには、多数の項目が並んでいます。
これらは、APIの一覧で、以下に代表的なAPIの概要を表にまとめました。

メニュー項目	内容例
Board	スクラムやカンバンのボード情報を取得・操作可能。 例：ボード一覧を取得、ボードのフィルターIDを取得など
Epic	エピック（大きな作業単位）に関するAPI。 例：エピックに関連する課題の取得や、エピックの情報取得など
Issue	課題（チケット）に関するAPI。 例：課題の取得・作成・更新・削除、コメント操作など
Sprint	スプリント（期間を区切った開発サイクル）に関するAPI。 スプリントの開始・終了・更新、所属する課題の取得など

実際のAPIを例に、公式ドキュメントの見方をマスターしよう

ここからは、実際にAPIページを見ながら、どこに何が書いてあるのかを一緒に確認していきましょう。

今回は一番基本的でよく使われる「課題（チケット）を取得するAPI」を例に、公式ドキュメントの読み解き方を解説します。

使用するAPIページ：The Jira Software Cloud REST API

Schooで無料講座をチェックする

該当APIの概要

「Returns a single issue, for a given …」のような英文の説明が続きますが、ざっくり言うと

このAPIは、指定された課題キーまたはIDに基づいて、その課題の詳細情報を返します。

という意味です。

パスパラメータの見方

次に、「Path parameters」という項目があります。ここでは、

Name	Type	Description
issueIdOrKey	String	取得したい課題のキー（例：TEST-123）またはID

と書かれています。

つまり、実際にAPIを使うときにはこの{issueIdOrKey}の部分を自分の課題キーに置き換えます。

リクエスト例

ページの右上部にはリクエスト例のセクションがあります。

たとえばPythonを選ぶと、以下のようなコードが表示されます。

赤字部分は皆さん自身の環境に合わせて変更する必要がありますが、基本的にはコピペして使えるので、まずは動かしてみるのがおすすめです！

access_tokenの取得方法は、【初心者向け】Jira API tokenの発行方法 | システムエンジニアの備忘録で詳しく紹介しているので、是非参考にしてみてください。

# This code sample uses the 'requests' library:
# http://docs.python-requests.org
import requests
import json

url = "https://your-domain.atlassian.net/rest/agile/1.0/issue/{issueIdOrKey}"

headers = {
  "Accept": "application/json",
  "Authorization": "Bearer <access_token>"
}

response = requests.request(
   "GET",
   url,
   headers=headers
)

print(json.dumps(json.loads(response.text), sort_keys=True, indent=4, separators=(",", ": ")))

まとめ