028. hx-headers（リクエストの「表紙」に情報を添える）

原理：通信の「マナーと身分証」

ヘッダーという目立たない主役

Webのブラウザとサーバーが会話（HTTPリクエスト）をするとき、実は目に見えるデータ（フォームの中身など）とは別に、「リクエストヘッダー」と呼ばれる、封筒の表書きのような情報がやり取りされています。

ここには通常、「どんなブラウザを使っているか」や「どんな形式のデータを受け取りたいか」といった、通信の基盤を支える重要な情報が書かれています。特に現代のWeb開発において、ヘッダーは以下のような「セキュリティ」や「特別な合図」のために非常に重要な役割を果たします： - APIキーの送付: 「私は正規の利用者ですよ」という証明。 - CSRFトークン: 「このリクエストは怪しいサイトからのなりすましではありません」という盾。 - モードの切り替え: 「今はデバッグモードで処理してほしい」という指示。

hx-headers 属性は、HTMXが行う通信のこの「表書き（ヘッダー）」部分に、あなたが独自の情報を書き込めるようにするためのツールです。

実践：セキュリティと特殊なリクエストの制御

1. セキュリティ（CSRFトークン）の送付

Webアプリを守るための「秘密の合言葉（CSRFトークン）」を、すべてのPOSTリクエストに添える例です。

<!-- index.htmlのbody付近などに一度書いておけば、
     その中のすべてのHTMXリクエストに自動で反映されます（継承） -->
<body hx-headers='{"X-CSRF-Token": "ABC-123-SECRET"}'>

    <button hx-post="/api/secure-action">
        安全なボタン
    </button>

</body>

2. API接続のための認証情報

外部のサービスや特別なAPIを叩く際に、認証用のキーを添える場合です。

<button hx-get="/api/external-service" 
        hx-headers='{"Authorization": "Bearer my-token-xyz"}'>
    外部データを取得
</button>

3. ステップ・バイ・ステップ解説

用途の確認: 送りたいデータが「ユーザーが見るべき中身」ではなく、「サーバーのシステムがチェックすべき管理情報」なら、hx-vals ではなく hx-headers を選びます。
フォーマット: hx-vals と同じく、JSON形式（{"名前": "中身"}）で記述します。
継承の活用: hx-headers は、親要素に書くと子要素のすべての通信に引き継がれます。個別のボタンに書くより、一番外側の <div> や <body> に書いて「共通設定」にするのが賢い使い方です。

比較：hx-vals vs hx-headers

hx-vals（中身）

役割: フォームのデータと同じように、プログラムの「メインの処理」に使う変数を送ります（例：search_query, user_id）。
見える場所: GET通信の場合、URL（?q=query）に表示されることもあります。

hx-headers（封筒）

役割: 通信そのものの「正当性」や「設定」を伝えます。セキュリティチェックなどは、ここで行われるのが一般的です。
見える場所: ユーザーには見えません。ブラウザの開発者ツール（ネットワークタブ）を開かない限り、ひっそりと影で働いています。

まとめ：初心者のための「信頼」の築き方

hx-headers を使いこなすと、あなたのWebアプリは一気にプロフェッショナルな「堅牢さ」を手に入れます。

セキュリティの盾に: サーバーが「このリクエストは本物かな？」と疑っているとき、hx-headers で正しいトークンを送ってあげれば、サーバーは安心して処理を進めることができます。
上位要素に任せる: 「すべての通信で同じヘッダーを送りたい」と思ったら、一度だけ広い場所に書いて、あとはHTMXの継承パワーに任せましょう。
名前のルール: X- で始まる名前（例：X-App-Version）にすると、独自のカスタムヘッダーであることが伝わりやすくなり、整理整頓された印象になります。

封筒の中身だけでなく、表書きまで丁寧に。hx-headers という心配りを通じて、サーバーからの信頼を勝ち取ってください。次の記事では、データを送る際の「荷造りの方法」を決める hx-encoding（029. hx-encoding）をご紹介します。