WebAPIの独自Headerを "X-" から始めるのはありかなしか

APIサーバーの仕様を検討している時に、headerに入れる独自パラメータの名前について一悶着（自己完結）あったので、メモ。

何を悩んだのか

例えば、URLには含みたくない secret のようなリクエストパラメータについて、独自にキー名を決めようと思います。

こんな感じ。

X-Secret : {secret}

なんなら良く使うあいつでも良いです。

X-Api-Key : {api-key}

で、なんかいい名前ないかなぁと思ってググってたら、こんなやりとりを見つけました。

stackoverflow / Custom HTTP headers : naming conventions

On June 2012, the deprecation of recommendation to use the "X-" prefix has become official as RFC 6648.

このやり取りの質問とベストアンサーだけ見て「なんだって！独自ヘッダに X- をつけるのは常識じゃないの？時代遅れなの！？」と色めき立ち、RFC本体を確認したり他にこれに関する情報がないか探したりしました。

こんな所でつまるのは私だけかもしれませんが、その時の記録。

結局、WebAPIの独自Headerを "X-" から始めるのはありかなしか

結論：あり

そもそもdeprecatedになった経緯が、

非標準のフィールドが標準になったときに発生した不便さのためです。

ということらしい。("X-"で始まるものがそのまま標準になるということは、力のあるor力をつけた企業・サービスが使っていたり、それを使うのが慣習になっていたと推測。)
推測するに2パターンの不便さがあって、
ケース1:
今まで独自ヘッダ X-Secret なんかを定義して、例えばパスワードの送信時のフィールドとして使っていたとする。これが急に標準ヘッダとして Secret がRFCで定義されたと。しかも意味が違って、標準の方ではここに鍵情報を入れる事になっていたりすると、 X-Secret の中身がどっちの意味で入ってきたか分かりにくい。
まだ対象のクライアントが限定的で、今までの独自ヘッダとしてしか使わないだろうと断言できるならまだしも、公開APIの場合は呼び出し側がどっちの意味で使っているのか確認が難しい。

ケース2:
あるサービスが X-Secret というヘッダを使っていた所、影響力が大きく他のサービスも同じく使いだした。そのうち X-Secret ヘッダはほぼ標準と言ってもいいほど一般的に使われるようになったとする。そのうちRFCで Secret が X-Secret の置き換えのヘッダフィールドとして定義され、今後は Secret を使うことを推奨される。ただ、RFCを皆が皆チェックして読むわけではないので、結局業界標準(RFC的には非標準)になってしまった X-Secret を使い続ける勢が後を絶たない。結局受ける側もずっと両対応し続けることになるし、送る側もどっちを送るのが正解かを悩み続けることになる。

じゃあどうすべきかというと、被らないような名前をつけるようにしましょう、というのが一つ。
例えば、組織のドメイン名やサービス名を含んだり、標準化はされなさそうなwordを選んだり。上記の例で言うと、 kusuwada-Secret とか。
もしくは himitsu-no-Secretとか。。。いや冗談です。
これだと、1. のケースでは自分が使っていたヘッダに似た標準フィールドができてもConfusingではなくなるし、2. のようにそのフィールドが一般的に広く使われるほど広まることは考えにくい。

ただ、"X-" から始まる名前をつけることにより、そのヘッダが独自定義のものであることがわかりやすい、と言うのは大きなメリット。
なので、被らなそうな"X-"から始まるフィールド名をつけるというのが、無難な選択肢かと。
ただ、今後広まってほしい・標準化したいと考えているフィールド名を付ける場合は、"X-"から始めないというのが良さそう。ただ標準化を狙いに行くような企業・サービスは滅多にないと思うので、大半の開発者は前者のほうを選択するのがよろしいかと。

ということで、結論はあり、ただしかぶりにくそうな名前にしておくのを推奨、かな。

最初のstackoverflowのやり取りも、ちゃんと読んでいけばそんな感じの内容の発言をしている人がいた。英語フィルターがかかって読み飛ばしていたわ・・・。

参考リンク

• stackoverflow / Custom HTTP headers : naming conventions
  

  • 今回のきっかけになった会話

• RFC6648: Deprecating the "X-" Prefix and Similar Constructs in Application Protocols

  • 問題のRFC

• Mozilla > Web technology for developers HTTP HTTP headers

  Custom proprietary headers can be added using the 'X-' prefix, but this convention was deprecated in June 2012, because of the inconveniences it caused when non-standard fields became standard in RFC 6648;

• 上記の日本語版

  'X-' 接頭辞を使用して独自のヘッダーを追加できますが、この慣習は 2012 年 6 月に非推奨になりました。これは、 RFC 6648 で非標準のフィールドが標準になったときに発生した不便さのためです。