RESTful APIとi18n：応答を設計する方法？

Question

私たちは、主に単一のクライアントのニーズを満たすことを目的としたRESTful APIを設計しています。非常に特殊な状況のため、このクライアントはできるだけ少ないリクエストを行う必要があります。

APIは、リクエストのAccept-Languageヘッダーを通じてi18nを処理します。これは、クライアントが単一のエンドポイントに対する要求の応答をすべての利用可能なロケールで保存する必要がある1つの機能を除いて、クライアントが実行する必要があるすべてのことに対して機能します。

クライアントが単一のリクエストですべての情報を取得できるように、一貫性のある構造化されたRESTful API設計を壊すことなく、どういうわけかAPIを設計できますか？

これまでに検討したオプション：

Accept-Languageヘッダーに複数のロケールを含めることを許可し、要求されたすべてのロケールのローカライズバージョンを応答に追加します。各ロケールは、ISO 639-1言語コードをキーとして識別されます。
そのエンドポイントに "？all_languages = true"パラメータのようなものを作成し、そのパラメータが存在する場合、応答で利用可能なすべてのロケールのローカライズバージョンを返します。
（上記のいずれもうまくいかない場合）クライアントからすべてのローカライズバージョンを取得するように複数のリクエストを作成します。

どちらが最善の選択肢ですか？

Jonathan Eunice · Accepted Answer

複数の言語を要求する2つの効果的な方法を説明しました。どちらでもうまくいくはずです。私は自分のコードに明示的な言語リクエストパラメータを選択します。

TL; DRバックストーリー

Accept-Languageヘッダーがあります。注、AcceptではなくAcceptedです。これは、HTTPコンテンツネゴシエーションの標準的な部分です。通常、レスポンスは Content-Language ヘッダーを元に戻します。

Accept-Languageは、一連のオプションを提供する始値です。 Content-Languageは、選択された言語を示す解像度です。ほとんどのContent-Language回答は単一の言語を返しますが、応答言語のコンマ区切りのリストを提供するオプションがあります。通常、それは混合コンテンツになりますが、複数のばらばらの代替案を通知できなかった理由はありません。クライアントが利用可能なすべての言語をリクエストするようにしたい場合は、ワイルドカードリクエストオプション*がすでにあります。

そのため、使用できるHTTPヘッダーメカニズムがすでにあります。ただし、可能なオプションの配列を提示し、単一のオプションを取り戻すことが多い交渉プロセスを便乗させることに注意してください。あなたは感覚を「ここにオプションのリストがあります、私にそれらすべてを与えてください！」にシフトするでしょう。あなたがそれで大丈夫なら、あなたは解決策を持っています。

ただし、HTTPヘッダーのシグナリングREST APIパラメータの適切性についてはかなりの議論があります。レストランに入るのと、ホストやマスターに詳細な注文を曖昧にするのとは少し異なります。ウェイターやウェイトレスが現れるのを待つよりも、それは機能します。たとえば、ホストに向けられた注文が飲み物や前菜に関連している場合は、ホストがすぐに確認できる、またはサーバーにすばやく通信できるものです。しかし、また、プロトコルの違反と見なされ、誤ったレベル/レイヤーまたは誤ったプレーヤーに対処されます。

2番目の選択肢は、明示的な要求パラメーターです。 ?all_languages=trueを提案します。これは具体的すぎるようです。 lang=en,fr,es（複数のリストされた言語を許可）またはlang=*またはlang=all（使用可能なすべての言語を指定）のようなものは、より一般的です。これは、URLまたはリクエスト本文で表現できます。

どちらの方法でも、多言語応答は簡単に返されたJSONペイロードにエンコードできます。

[ { "lang": "en", "content": "As Gregor Samsa awoke one morning..." }, { "lang": "de", "content": "Als Gregor Samsa eines Morgens..." }, ... ]

結局のところ、これらのアプローチはどちらもうまくいくはずです。どちらも、「一貫性があり、構造化されたRESTful API設計」と見なすことができます。 HTTPコンテンツネゴシエーションヘッダーをピギーバックする（そして通常の感覚を少し変更する）ことに対する適切な態度に基づいて、どちらがより良いかに関する決定は、主にあなたに依存します。

私自身の好みは、APIリクエストの同等の部分として、ヘッダーと他のパラメーターを混合しないことです。明示的なlangまたはlanguageパラメータは、私にはわかりやすく見えます。ただし、HTTP動詞（例：GET、PUT、POST、PATCH、...）はヘッダーの一部であり、/リクエストの解釈と混ざり合って、私はエンベロープとコンテンツの区別が少し人工的で曖昧であることを認めます。ほとんどの設計決定と同様に、本物の専門家は別の方法で答え、YMMVを使います。