【入門編】 APIのタイムアウト設計（コネクション、読み取り、書き込み） – Web APIアーキテクチャ・データ連携実践ガイド

こんにちは！ネットワークとAPIの旅へようこそ。インフラアーキテクトの私です。

Webアプリケーションを作ったり、外部の便利なAPI（お天気情報や決済サービスなど）と連携したりするとき、「APIのタイムアウト設計」という言葉を聞いたことはありませんか？
「なんとなく標準のままで動かしているけれど、たまに通信がフリーズして困る…」「サーバーがエラーを出しているのか、クライアントが待ちくたびれて諦めたのか分からない…」そんなモヤモヤを抱えている方も多いのではないでしょうか。

今回は、ネットワークの裏側で何が起きているのかを、身近な「郵便配達」の世界にたとえながら、優しく、そして実践的に紐解いていきましょう。難しい専門用語はいったん脇に置いて、一歩ずつ理解していきましょうね！

—

1. 郵便配達でイメージする「3つのタイムアウト」

APIの通信は、私たちが手紙や荷物を送るやり取りとそっくりです。
あなたが遠く離れた友人に、特大の荷物を送る場面を想像してみてください。ここで、通信の「タイムアウト（待ちくたびれて諦めること）」には、大きく分けて以下の3つのステップが存在します。

1. コネクション（接続）タイムアウト

「相手の家（サーバー）にたどり着けるか？」のタイムアウトです。インターホンを押しても、そもそも誰も出てこない、あるいは道に迷って家が見つからないときに「これ以上待つのはやめよう」と諦める時間です。

2. リード（読み取り）タイムアウト

「相手が荷物を包んで自分に送り返してくれるのを待つ時間」です。「今から荷物を準備するから待ってね」と言われたあと、いつまで経っても荷物が出てこないときに「待ちくたびれた！」と帰る時間です。

3. ライト（書き込み）タイムアウト

「自分が相手に荷物を渡し切るまでの時間」です。大きな荷物をドアから運び出すのに、手が滑ったりしてモタモタしているときに「早くして！」と打ち切られる時間です。

APIの世界でも、これら3つのタイマーを適切に設定してあげる必要があります。どれか一つでも抜けていると、ネットワークの片隅で通信が永遠に終わりを告げず、システム全体の動きが止まってしまう「フリーズ現象」を引き起こしてしまうのです。

—

2. クライアントとサーバー、どちらがタイマーを持つべき？

「タイムアウトって、どこで設定すればいいの？」という疑問が湧きますよね。
結論から言うと、「クライアント側（お願いする側）」と「サーバー側（お願いされる側）」の両方で設定するのが鉄則です。

例えば、クライアント側だけで「10秒待ったら諦める」と決めていても、サーバー側が「私は30秒かけてじっくり処理するもんね」とマイペースで作業していると、どうなるでしょうか？
クライアントが10秒で「もう待てない！」とプッツリ電話を切った後も、サーバー側はせっせと処理を続け、データベースを更新し続けてしまいます。これが、システムの世界で大問題になる「処理の不整合（すれ違い）」の原因です。

現場でよくある悲劇：二重決済の恐怖

クレジットカード決済のAPIを想像してみてください。
クライアント側（スマホアプリ）が「決済して！」とお願いし、サーバーが裏側で決済処理を始めました。しかし、ネットワークの調子が悪くてなかなか返事が返ってきません。
スマホアプリ側のタイムアウト（例：5秒）が来てしまい、画面には「タイムアウトエラーが発生しました」と表示されました。焦ったユーザーがもう一度「決済ボタン」を押したところ、実は1回目の裏側処理も遅れて無事に完了しており、結果的に2重でお金を請求されてしまった……！

こんな悲劇を防ぐためにも、タイムアウトの設計と「二重リクエストを防ぐ工夫（冪等性：べきとうせい）」のバランスがとても大切になります。

—

3. 実践！コードと設定で見るタイムアウトのバランス

それでは、実際の開発やインフラ構築の現場で、どのようにタイムアウトを書き下ろしていくのかを見ていきましょう。今回は、Pythonの代表的なHTTPクライアントである requests ライブラリと、Webサーバーの代表格である Nginx の設定を例に取ります。

クライアント側（Python）のコード例

PythonからAPIを呼び出す際、timeout 引数を使って「接続」と「読み取り」の時間を指定します。

import requests
from requests.exceptions import Timeout

# 接続先のエンドポイントURL
api_url = "https://api.example.com/v1/orders"

# 送信したいデータ
order_data = {"item_id": "12345", "quantity": 2}

try:
    # タイムアウトの設定
    # タプル形式で指定: (コネクションタイムアウト, リードタイムアウト)
    # ここでは「接続に3秒、データの読み取りに5秒」を超えたら諦める設定にしています
    response = requests.post(api_url, json=order_data, timeout=(3.0, 5.0))
    
    # HTTPステータスコードがエラー（400番台や500番台）の場合に例外を発生させる
    response.raise_for_status()
    
    print("注文が成功しました！:", response.json())

except Timeout:
    # タイムアウトが発生した場合の優しいていねいなエラーハンドリング
    print("通信がタイムアウトしました。電波の良い環境で再度お試しいただくか、注文履歴をご確認ください。")

except requests.exceptions.RequestException as e:
    # その他の通信エラー
    print(f"通信エラーが発生しました: {e}")

このように、クライアント側では「いつまでも待ち続けずに、必ず諦めるライン」を明示しておくことが、ユーザー体験を守る第一歩になります。

サーバー側（Nginx）の設定例

次に、リクエストを受け止めるサーバー側のインフラ設定（Nginx）を見てみましょう。サーバー側では、クライアントからデータを受け取る時間や、バックエンドのプログラムから返事をもらう時間をしっかりと制御します。

server {
    listen 80;
    server_name api.example.com;

    # クライアントからリクエストボディ（送信データ）を受け取る際のタイムアウト
    # データをダラダラと送り続けてくる行儀の悪い接続を切断します
    client_body_timeout 10s;

    # クライアントへレスポンスを書き込む（送信する）際のタイムアウト
    client_header_timeout 10s;

    # バックエンドのアプリケーションサーバー（uWSGIやNode.jsなど）からの応答を待つタイムアウト
    # 重い処理であっても、最大30秒で一旦区切る設定にしています
    proxy_read_timeout 30s;

    # バックエンドへデータを送信する際のタイムアウト
    proxy_send_timeout 30s;

    location / {
        proxy_pass http://127.0.0.1:8000;
        # ヘッダー情報の引き継ぎなど
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

ここで重要なのは、「クライアント側のタイムアウト時間＜サーバー側のプロキシタイムアウト時間」にしないこと、あるいはその逆の設計思想をチーム全体で共有することです。一般的には、サーバー側が少し長めに待ち、クライアント側が先に諦めることで、サーバーが途中で処理を投げ出してしまうのを防ぎます（または、非同期処理キューを使って即座に「受け付けました」と返す設計にします）。

—

4. まとめ：美しいAPI設計は「思いやり」から生まれる

今回は、APIのタイムアウト設計について、郵便配達のたとえや具体的なコードを交えて解説しました。

コネクション、リード、ライトという「3つの待ち時間」を意識する。
クライアントとサーバーの両方で適切にタイマーを設定し、フリーズや不整合を防ぐ。
万が一タイムアウトしたときのユーザーへの配慮（エラーメッセージや二重処理の防止）を忘れない。

ネットワークの世界は目に見えないからこそ、こうした小さな「待ち時間のルール」を丁寧に決めてあげることで、トラブルに強く、ユーザーに優しい美しいシステムができあがります。

インフラやネットワークの基礎は、日々の泥臭い工夫と、ちょっとした思いやりの積み重ねです。ぜひ今日の開発から、タイムアウトの数値を意識してみてくださいね！それでは、また次回の技術の旅でお会いしましょう！