【ITニュース解説】Serving HTML and Markdown from one public URL

WebサイトやAPIが、ユーザーや他のプログラムに対して情報を提供する際、同じ内容でも異なる形式で提供する必要がある場合がある。この記事では、一つの公開URLを通じて、HTML形式とMarkdown形式の両方の情報を配信する方法について解説する。これは、情報を利用する側がどのような形式を求めているかに応じて、サーバーが適切な形式を返す「コンテンツネゴシエーション」という技術を中心に据えている。

私たちがWebブラウザでWebサイトを見ると、通常はHTML形式のコンテンツが表示される。HTMLは、テキストだけでなく、画像、リンク、動画などを構造的に表現でき、ブラウザが視覚的にわかりやすいページとしてレンダリングするための標準的な形式だ。しかし、Webサイトの情報をプログラムで読み取ったり、ドキュメント作成ツールで再利用したりする場合、Markdownのようなよりシンプルなテキスト形式の方が都合が良いこともある。Markdownは、軽量なマークアップ言語で、シンプルな記法でテキストの構造や装飾を表現できるため、多くの開発者や技術者に利用されている。

この技術の根底にあるのは、単にファイルの拡張子を変えるだけでは不十分だという考え方だ。サーバーからの応答は、その内容がどのような形式であるかを明確に示し、情報を受け取るクライアント（WebブラウザやPythonスクリプトなどのプログラム）の好みを尊重し、さらに、プライベートな情報へのアクセスルールを誤って変更してしまわないように注意する必要がある。

具体例として、Giorgioというプロジェクトの公開エンドポイントが使われている。このプロジェクトは、シンプルだが再現性の高いHTTP通信の契約を結ぶことを目的としている。それは、一つのカタログエンドポイント、公開ページの二つの異なる表現、そしてプライベートなルートへの明確な境界線を持つことだ。公開されている情報を見るために、特別なアカウントや認証情報は一切必要ない。

まず、「公開カタログ」について見ていこう。これは、Webサイトの公開されている情報（ページのURLなど）を一覧で提供するエンドポイントだ。例えば、https://giorgiobm.com/api/public/site というURLにアクセスすると、サイト全体の公開メタデータが返される。このエンドポイントは、データ分析を行ったり、コードを実行したり、ユーザーアカウントを管理したり、プライベートな会話やファイルを公開したりするような機能は持たない。純粋に、公開されているサイトの構成情報を提供するだけだ。

Pythonを使ってこのカタログ情報を読み取る簡単なスクリプトが示されている。このスクリプトは、urllib.request という標準ライブラリを使って指定のURLにリクエストを送信し、返ってきたJSONデータを解析している。ここで注目すべきは、HTTPリクエストのヘッダーに「Accept: application/json」と「User-Agent: GiorgioPublicReader/1.0」が設定されている点だ。「Accept: application/json」は、クライアントがJSON形式のデータを希望していることをサーバーに伝える。「User-Agent」は、リクエストを送っているクライアントが何であるかをサーバーに識別させるための情報だ。例では、Pythonのデフォルトのリクエストがサーバーの不正利用対策フィルターによってHTTP 403（アクセス拒否）エラーになったのに対し、適切なUser-Agentを設定したクライアントはカタログ情報を取得できたという事例が紹介されている。これは、公開エンドポイントであっても、悪意のあるアクセスや不正利用を防ぐためのフィルタリングが施されている場合があることを示している。したがって、システムエンジニアとしてこのようなWebサービスを扱う際には、サーバーからの応答ステータスを注意深く確認し、安易にリトライしたり、すべての応答がJSON形式だと決めつけたりしないことが重要だ。

次に、Markdown形式の要求についてだ。特定の公開ページ（例えば https://giorgiobm.com/about）に対して、curl コマンドを使って「Accept: text/markdown」というヘッダーを付けてリクエストを送信すると、サーバーはそのページのMarkdown形式の表現を返してくれる。もちろん、HTMLを好むクライアントに対しては、引き続きHTML形式が提供される。もし Accept ヘッダーに「text/markdown」と「text/html」の両方が指定され、HTMLの方が品質値（qパラメータ）が高いと設定されていれば、サーバーはHTMLを返すこともあり得る。サーバーからの応答には「Content-Type」というヘッダーが含まれており、これを見ることで実際に返されたデータがHTMLなのかMarkdownなのかを正確に判断できる。また、これらの異なる表現はキャッシュに区別して保存されるよう、「Vary: Accept」というヘッダーが設定されることで、Webサーバーのキャッシュ機構が正しく動作するようにしている。

ただし、Webサイトのすべての情報がこのようにコンテンツネゴシエーションの対象となるわけではない。記事では、プライベートなチャットやコードセッションのルートは、この公開コンテンツネゴシエーションの範囲外だと明言されている。また、公開カタログはあくまで「読み取り専用」であり、POSTメソッドを使ってAIによる補完を要求するような代替手段ではないことも強調されている。これは、公開される情報とプライベートな情報、そして利用可能な操作の種類について、明確な境界線を設けることの重要性を示している。

APIやWebサービスを開発・運用する上で、ドキュメントの一貫性も非常に重要だ。例えば、OpenAPIドキュメントは、実際に利用可能な操作やエンドポイントを正確に記述するべきだ。サイトマップは、正規の公開URLをリストアップするべきであり、ナビゲーションのサマリーはクライアントがページを発見するのに役立つが、その存在が直ちにそのページがアクセス可能であることや、検索クローラーが訪問したことを証明するものではない。公開エンドポイントが提供しない認証フローや、プライベートな操作、あるいは公開されていないSDKについて、ドキュメントに含める必要はない。むしろ、小さく正確なインターフェースの方が、検査しやすく、ドキュメント化も容易になる。

そして、動作確認の重要性だ。単にファイルがローカル環境に存在しているだけでは、それがホストされているルートから正しく提供されているとは限らない。例えば、静的アセットの優先順位設定によって、期待とは異なるファイルが提供される可能性もある。そのため、HTMLとMarkdownの表現が期待通りか、正規のメタデータが正しいか、Acceptヘッダーによるネゴシエーションが機能しているか、存在しないページにアクセスした際に正しいエラーが返されるか、サポートされていないHTTPメソッドが拒否されるか、そして何よりもプライベートなルートが誤って公開されていないかなど、実際に公開環境で動作を確認することが不可欠だ。これらのインターフェースは公開情報のアクセス性を向上させるが、それが即座に検索エンジンにインデックス登録されることや、AIアシスタントがその製品を推奨すること、あるいはモデルがそのコンテンツを学習に利用したことにはならない。情報を利用する側は、実際に検査したページを引用し、その内容の限界を理解しておくべきだ。

最後に、不具合を報告する際の効果的な方法についても触れられている。障害を報告する際には、問題が発生したURL、使用したHTTPメソッド、Acceptヘッダー、期待されるHTTPステータスコード、そして実際に観察されたレスポンスのタイプを含めるべきだ。しかし、アカウントの資格情報やプライベートなワークスペースデータは決して含めてはならない。これにより、有用なバグ報告書を作成できると同時に、単なるHTTPリクエストの成功が、Webページのインデックス登録、AIモデルのトレーニング、あるいは回答の品質を証明するものではないという認識を持つことが促されている。

この解説を通じて、システムエンジニアを目指す初心者は、Webサービスが多様な形式のコンテンツをいかに効率的かつ安全に提供しているか、そしてその裏側にある技術的な配慮や開発のベストプラクティスについて、基本的な理解を深めることができるだろう。