Python API

Python で API を扱うときは、単に「外部の機能を呼ぶ」だけでなく、認証、リクエストの作り方、返ってきたデータの扱い方までをひとまとめに考える必要があります。特に業務システムやクラウド API では、HTTP の基本と Python のライブラリの両方を押さえると、実装の見通しが大きく良くなります。

Python から見た API の入口

Python API という言い方は少し広く、実際には「Python から使う API クライアント」や「Python で作る API サーバー」を含むことがあります。ただ、実務でよく話題になるのは、Python のプログラムから Web API にアクセスするケースです。たとえば、データ取得、帳票の自動作成、クラウドの設定変更、監視結果の収集などで使われます。

Python では標準ライブラリだけでも HTTP 通信はできますが、実際には `requests` のような外部ライブラリを使うことが多いです。JSON を送受信する API では、Python の `dict` と JSON の対応を理解しておくと、データ変換で迷いにくくなります。

リクエストとレスポンスの基本形

多くの Web API は、URL、HTTP メソッド、ヘッダー、本文の 4 点で決まります。Python ではこれらをコードで組み立てて送信し、返ってきたレスポンスのステータスコードと本文を確認します。

import requests

url = "https://api.example.com/items"
headers = {"Authorization": "Bearer YOUR_TOKEN"}
payload = {"name": "sample", "count": 3}

res = requests.post(url, headers=headers, json=payload, timeout=10)
print(res.status_code)
print(res.json())

この例では、`json=payload` と書くことで Python の辞書を JSON として送れます。`timeout` を付けるのは、通信が止まったまま待ち続けないためです。API 呼び出しは「成功するのが前提」ではないので、失敗時の分岐も最初から入れておくのが基本です。

認証まわりの組み立て

Python API でつまずきやすいのが認証です。API キー、OAuth 2.0 のアクセストークン、サービスアカウントなど、方式によって準備の仕方が変わります。単に「ヘッダーに入れる」だけで済むものもあれば、トークンの更新処理まで必要なものもあります。

• API キー型: 比較的単純で、ヘッダーやクエリ文字列にキーを付けて使う
• OAuth 2.0 型: ユーザーや組織の権限を扱うため、認可の流れが必要になる
• サービスアカウント型: サーバー間通信でよく使い、秘密鍵や権限設定の管理が重要になる

認証情報をコードへ直書きするのは避け、環境変数や秘密管理の仕組みを使うのが一般的です。とくに Python はスクリプトとして配布されやすいため、認証情報の混入に注意が必要です。

Python での失敗処理と再試行

API は相手先の状態に左右されるので、ネットワーク障害や一時的な制限に備える必要があります。Python 側では、HTTP の状態コードに応じて処理を分け、必要なら再試行します。たとえば 429 はレート制限、500 系は相手側の一時障害として扱うことが多いです。

再試行は便利ですが、むやみに繰り返すと相手先に負荷をかけます。待ち時間を少しずつ伸ばす指数バックオフを使うことが多く、バッチ処理や自動化では特に有効です。例外処理では、通信エラーと API の業務エラーを分けて考えると、原因追跡がしやすくなります。

JSON と Python の型の対応

Python API では、JSON の構造をどう扱うかが重要です。JSON はオブジェクト、配列、文字列、数値、真偽値、null でできていますが、Python では主に `dict`、`list`、`str`、`int`、`float`、`bool`、`None` に対応します。

受信データは、まず全体の形を確認してから必要な項目を取り出すのが安全です。入れ子が深い場合は、途中のキーが存在しない可能性もあるため、例外や `get()` を使った防御的な書き方が役立ちます。

ライブラリ選びで変わる実装の重さ

Python API の実装は、使うライブラリで書き味が変わります。標準ライブラリは追加依存が少なく、環境を選びにくい反面、少し記述が長くなることがあります。対して `requests` のような外部ライブラリは読みやすく、実務では扱いやすいことが多いです。

また、同期処理だけで十分か、非同期処理が必要かも判断ポイントです。大量の API を順番に叩くなら、並列化や非同期化で全体の待ち時間を減らせます。ただし、API の利用規約やレート制限を超えない設計が前提です。Python API では「速さ」だけでなく、「相手先に無理をさせないこと」も実装条件になります。

Webhook と比べたときの考え方

Python API は、こちらから要求して結果を取りに行く「呼び出し型」です。一方、Webhook は相手からイベント通知を受け取る「受信型」です。どちらも自動化でよく使いますが、役割が異なります。

実際のシステムでは、Webhook を受けて Python が API を呼び返す、という組み合わせも多いです。API だけで完結するとは限らず、イベント駆動の入口として Webhook を置く設計もよくあります。

Python API を理解するうえでは、HTTP の基礎、JSON の型変換、認証方式、失敗時の処理をセットで押さえることが大切です。単に「Python で外部につなぐ」という意味ではなく、通信の約束事を Python のコードに落とし込む技術だと考えると、設計の全体像が見えやすくなります。