RESTful APIとi18n:応答を設計する方法は?


15

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

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

クライアントが単一のリクエストでこれらすべての情報を取得できるように、一貫性のある適切に構造化されたRESTful API設計を壊さずに、何らかの方法でAPIを設計できますか?

これまで検討してきたオプション:

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

どれが最良の選択肢ですか?

回答:


22

複数の言語を要求する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動詞(例えば以来GETPUTPOSTPATCH、...)ヘッダの一部、およびへ/要求の解釈と混在も重要であり、私は封筒対コンテンツ区別を認めるビット人工ファジーです。ほとんどの設計上の決定と同様に、本物の専門家は別の方法で答え、YMMV。


彼らの反応は非常に教育的で有益でした。ありがとうございました。また、Accept-not-Acceptedに気づいてくれてありがとう。私たちのコードでは正しいのですが、投稿を書くときに適切な用語を使用できませんでした。さらに参照するために変更します。
AMM
弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.