Python で HTTP API を呼び出すための環境構築から実装まで

## はじめに

REST API のような HTTP API を Python から呼び出す際、標準ライブラリの urllib も使用できますが、外部ライブラリの`Requests`を使用すると、より簡単で直感的にリクエストを送信できます。

> 参考リンク:
>
> - [Requests 公式ドキュメント](https://requests.readthedocs.io/en/stable/)
> - [GitHub リポジトリ](https://github.com/psf/requests)

`Requests`に限らず、外部ライブラリを使用する際は、適切な開発環境の準備が重要です。

### なぜ環境を分ける必要があるのか？

Python で外部ライブラリを導入する際、環境を分けずに `pip install` 等を実施して端末内にインストールする方針にすると、以下のような問題が発生する可能性があります：

- 異なるプロジェクト間でのライブラリのバージョン競合
- 端末内にインストールされている Python パッケージへの意図しない影響
- チーム開発時の環境の再現性の低下

これらの問題を防ぐために、プロジェクトごとに独立した環境を作成することが推奨されます。
そこで使用するのが Python の仮想環境（venv）です。

## 仮想環境（venv）の準備

### venv とは？

Python の仮想環境（venv）は、プロジェクトごとに独立した Python 環境を作成できる機能です。
これにより下記が実現できます。

- プロジェクトごとに異なるバージョンのライブラリを使用可能
- 端末内の Python 環境を汚さない
- 依存関係の管理が容易
- プロジェクトの移植性が向上

### venv の作成

まず、プロジェクトのルートディレクトリで仮想環境を作成します：

```bash
python -m venv .venv # .venvは一般的な命名規則
```

これで、プロジェクトのルートディレクトリ直下に仮想環境に必要なファイル群を含む `.venv` ディレクトリが作成されます。

### venv の有効化

venv の有効化は、プロジェクトを使用する際 (例えば Terminal の起動時) に毎回実行が必要です。

#### Windows での有効化：

```
.\.venv\Scripts\activate
```

#### macOS/Linux での有効化：

```bash
source .venv/bin/activate
```

## 依存関係の管理と Requests ライブラリのインストール

### requirements.txt の作成

プロジェクトの依存関係のある外部ライブラリを `requirements.txt` に記載します :

```text
requests>=2.32.3  # 最小バージョンを指定
```

> 参考：[requirements.txt の形式について](https://pip.pypa.io/en/stable/reference/requirements-file-format/)

### ライブラリのインストール

仮想環境を有効化した状態で `pip install` を実行することで、仮想環境内にライブラリがインストールされます。

```bash
pip install -r requirements.txt
```

## Requests を使用した API の呼び出し

上記までで Requests ライブラリが使用できるようになったので、API の呼び出しの実装が進められます。

### 基本的な使い方

非常にシンプルに HTTP リクエストを送信できます。

```python
import requests

# GET リクエスト
response = requests.get("https://example.com/data")

# POST リクエスト
data = {"key": "value"}
response = requests.post("https://example.com/create", json=data)

# リクエストヘッダーの追加
headers = {
    "Authorization": "Bearer your-token",
    "Content-Type": "application/json"
}
response = requests.get("https://example.com/secure", headers=headers)

# リクエストパラメータの追加
params = {
    "query": "python",
    "page": 1
}
response = requests.get("https://example.com/search", params=params)
```

### レスポンスの取得

レスポンスは、`get` 等の戻り値のオブジェクトに格納されています。

```python
# JSON レスポンスの取得
data = response.json()

# テキストレスポンスの取得
text = response.text

# レスポンスヘッダーの取得
headers = response.headers
```

## HTTP ステータスの処理

ステータスコードも `get` 等からの戻り値のオブジェクトに格納されています。

ステータスコードの確認時、4xx や 5xx のエラーの際は例外を発生させたい場合があると思います。
その場合は下記のように `get` 等からの戻り値のオブジェクトで、`raise_for_status()` を実行することで `HTTPError` を発生させることができます。

```python
import requests

try:
    response = requests.get("https://example.com/data")

    # レスポンスの確認
    response.raise_for_status()  # 4xx/5xx エラーの場合は例外を発生

except requests.exceptions.HTTPError as e:
    # HTTP エラーの処理
    if e.response.status_code == 404:
        print("リソースが見つからない")
    elif e.response.status_code == 401:
        print("認証が必要")
    else:
        print(f"HTTP エラー: {e.response.status_code}")

except requests.exceptions.ConnectionError:
    print("接続エラー")

except requests.exceptions.Timeout:
    print("タイムアウト")
```

## まとめ

- venv を使用することで、クリーンな開発環境を維持できる
- Requests ライブラリを使用することで、簡単に HTTP API を呼び出せる
- 適切なエラーハンドリングにより、安全な API 呼び出しが可能
- ステータスコードに応じた処理を実装することで、より堅牢なアプリケーションを作成できる