RESTful APIのためのメイメット

Question

Sun Cloud API（http://kenai.com/projects/suncloudapis/pages/Home）は、RESTfulなAPIのための良い例です。 RESTfulな原則に従えば、リソースを取得したときに、そのリソースの表現をもはや少なくすることはありません。

レスポンスのContent-Typeヘッダーは、そのリソースの種類を正確に示します。たとえばapplication/vnd.com.sun.cloud.Snapshot + jsonです。 SunはこれらのMIMEタイプをIANAに登録しています。

これは現在一般的にどの程度実用的ですか？私が見たほとんどのAPIは、 "application/json"のContent-Typeを使用しています。これは、レスポンスがJSONであることを示していますが、それ以上は何もありません。 JSONオブジェクトには、それが何であるかを知るために、「型」プロパティのようなものが必要です。

私はRESTful APIを設計しています（これは公開されないため、mimetypesを登録しません）。私はRESTEasyを使用しており、完全なMIMEタイプを指定しても、応答ヘッダーのContent-Typeは、Accept要求ヘッダーが指定したものとまったく同じであることがわかります。リクエストが "application/* + json"を要求する場合、レスポンスヘッダは "application/* + json"になります。私はおそらく応答が出る前にヘッダーを変更することでこれを修正することができますが、私はそれをやろうとするべきですか？または、リクエストに同じようにワイルドカードが返されるべきですか？

また、ほとんどのAPIのように、「application/json」を提供するだけでいいですか？後で追加

追加思考：私は、プロトコルとしてHTTPを使用すべきか、私は自分のプロトコルをラップするだけで転送メカニズムとしてHTTPを使用する必要があります。

質問を述べる別の方法はありますか？

HTTPをプロトコルとして使用するには、応答のエンティティ本体に要求されたオブジェクトの表現（またはエラーメッセージオブジェクトの表現）が含まれ、「Content-Type」ヘッダーにはオブジェクトの正確なタイプが含まれ、 "Status"ヘッダーには成功またはエラーコードが含まれています。

HTTPを単なるトランスポートメカニズムとして使用するには、 "Status"ヘッダーが常に200 OKに設定されます。 "Content-Type"は "application/json"のような一般的なもので、エンティティ本体にはオブジェクト、オブジェクトの種類、エラーコード、その他の必要なものが含まれます。独自のプロトコルがRESTfulである場合、全体のスキームはRESTfulです。 （HTTPはRESTfulなプロトコルですが、唯一のプロトコルではありません）

独自のプロトコルはすべてのトランスポートレイヤーに対して不透明です。プロトコルとしてHTTPを使用する場合、すべてのトランスポートレイヤーはそれを理解して、望ましくないことを行う可能性があります。たとえば、ブラウザで「401 Unauthorized」のレスポンスを傍受し、自分で処理したい場合でもログインダイアログを表示します。

Answer 1

また、ほとんどのAPIのように「application/json」を提供する必要がありますか？

私はそうは思いません。

RESTful Webアプリケーションとそれを使用するクライアントを結合するのは、メディアタイプだけです。メディアタイプのドキュメントは、APIのドキュメントです。メディアタイプは、クライアントとアプリケーションの間の契約です。特定のメディアタイプを排除し、RESTを実行可能にする重要な要素を排除します。

サンは、これらのMIMEタイプをIANAに登録しました。

any mention of that hereが見つかりませんでした。 AFAIKでは、カスタムメディアタイプをIANAに実際に登録する必要はありません。規約は、名前空間の競合を防ぐapplication/vnd.com.example.app.foo + jsonの逆のドメイン表記を使用するように思われます。あなたのメディアタイプが安定し公開されている場合は、それが良い考えかもしれませんが、要件はありません。しかし、これで間違っている可能性があります。

Answer 2

完全なmimetypeを指定して値を取得しますか？ mimetypeがapplication/jsonの場合とは異なる完全なmimetypeを使って何かをしますか？

私の2セント - APIが公開されない場合、完全なMIMEタイプの理由はありません。アプリケーション/ jsonのmimetypeは十分以上でなければなりません。応答が戻ってきたjsonのタイプはすでに分かっています。 APIが最終的に公開される場合は、完全なMIMEタイプについて心配してください。

Answer 3

多くの自分の表現には、自分のvnd.mycompany.mymediatype + xmlメディアタイプを使用します。クライアントでは、返された表現のメディアタイプに基づいて適切なコントローラクラスにディスパッチします。これにより、実際にサーバーはリンクをたどったユーザーに応答してクライアントアプリケーションの動作を制御することができます。

個人的には、RESTクライアントをサポートしたい場合は、application/xmlとapplication/jsonを使用するのが最悪の選択肢の1つであると私は考えます。唯一の例外は、クライアントがダウンロードしたコード（Javascriptなど）を使用してデータを解釈する場合です。