RESTful Web APIのカスタムMIMEタイプはいくつですか？

Question

RESTful Web APIは、主要なクラスのリソース（顧客、予約、HotelRoomなど）ごとにベンダー固有のカスタマイズされたMIMEタイプを使用するか、APIがすべてのリソースにわたって単一のベンダー固有のMIMEタイプを共有する必要がありますか？

一方、各リソースは異なるフィールドを持ち、たとえば新しい顧客を受け入れる可能性のあるエンドポイントは新しい注文を受け入れることができないため、リソースは異なります。

しかし、Rest Worst Practicesは、これがクライアント側での解析を複雑にする可能性があるため、これがA Bad Thing（tm）であることを示唆していますが、それ以上の詳細は示されていません。私は間違いなくこれを有効な懸念事項として見ることができます。リソースタイプごとのアプローチに従えば、埋め込まれた非匿名エンティティのコレクションの種類ごとにカスタムタイプを作成し続けることさえあるようです。

Answer 1

@decezeによって残されたコメントを拡大する：あなたはそれを必要としません。 "ベンダー固有のカスタマイズされたMIMEタイプ"を別のものと混同する可能性はありますか？

すべてのリソース（またはその両方に応じて）に対して、application/jsonまたはapplication/xmlを送信することを制限できなかった理由はわかりません。

もちろん、各リソースの構造は完全にそれぞれのフィールドに依存しますが、（JSONを選択している場合は）JSONハッシュとしてそれらすべてを提供することはできます。

Answer 2

RESTfulなWeb APIは、リソースの各主要クラス（例えば顧客、予約、 HotelRoom、など）、またはすべきAPIを共有し、単一のベンダー固有のMIME タイプのために、ベンダー固有のカスタマイズされたMIMEタイプ を使用すべきすべてのリソースにわたって？

実際にはクライアントをサーバーから切り離すわけではないので、それは単なる粗い解決策です。

しかし、残りワーストプラクティス として、これは悪いこと（TM）であることを示唆している、これは、クライアント側での解析を超える複雑にすることができますが、その

はい超え 多くの詳細を与えるものではありませんそれは本当です。例えばRESTパートのオープンリンクデータやヒドラのような標準的なボキャブのRDFなど、きめ細かなソリューションを使用する必要があります。

Answer 3

実用的に考える。 MIMEタイプは、「インターネットメディアタイプは、インターネットを介してファイルフォーマットを標準化するための2つの部分からなる識別子です」と定義されています。つまり、データの形式が変更されている場合（TXT-> HTML-> JSON-> XML-> YAML-> CSV-> ...）、MIMEタイプを変更する必要があります。

しかし、上記のJoshua Beldenによって特に言及された、他の完全に有効な用途があります。次に、APIのバージョンを確認するためのhow GitHub uses MIME typeの例を示します。

現在のバージョン

はデフォルトでは、すべてのリクエストは、APIのV3バージョンを受けます。このバージョンをAccept ヘッダーを通じて明示的にリクエストすることをお勧めします。

受け入れ：アプリケーション/ vnd.github.v3 + JSON

それはAPIのv3のバージョンに送信されたv2のリクエストのデータレイアウトは、彼らが同じに存在するにもかかわらず、互換性がないだろうという意味がありますURL（およびその逆）。 APIのあるバージョンから次のバージョンに移行するために必要な変更を減らすのにも役立ちます（たとえば、URLを更新する必要はありません）。

つまり、バージョン固有のAPIを「将来的に証明する」ために、アプリケーションでデフォルトでカスタムMIMEタイプを使用する必要はありません。アプリケーションに大量の外部消費者がいる大規模な外部APIがない場合は、カスタムバージョンのMIMEタイプは必要ありません。

また、REST APIエンドポイントは、MIMEタイプではなく、生成および消費されるデータの構造を決定する必要があります。たとえば、GET "/ customers/5"は、Customerエンティティからシリアライズされたデータのみを生成します。 POST/"reservations" は、予約エンティティに対して適切に非直列化されるデータのみを消費します。つまり、エンドポイントのシリアライゼーションが構文チェックを処理し、400レベルのコードを返し、提供されたデータが適切に構造化されていないことを説明する必要があります。

この動作を強調するGitHubのAPIの別の例です。

HTTP/1.1 422 Unprocessable Entity 
Content-Length: 149 

{ 
    "message": "Validation Failed", 
    "errors": [ 
    { 
     "resource": "Issue", 
     "field": "title", 
     "code": "missing_field" 
    } 
    ] 
} 

それをすべてまとめると、ほとんどのシリアル化フレームワークは、「アプリケーション/ JSON」と「アプリケーション/ XML」を処理することを期待し、「箱から出して」きます。カスタムベンダ特有のMIMEタイプを確実に追加することはできますが、圧倒的な理由がなければどうしてですか？

このレスポンスでゾンビの質問を作成したばかりの場合は申し訳ありません。

Answer 4

MIMEタイプを使用すると、RESTリソースをその表現（json、xml、pdfなど）から分離することができます。これにより物事の結合が弱くなりますが、理想はリソースのスキーマを定義するのにそれを使用するのではなく、の書式です。

一方、各リソースは異なるフィールドを持ち、たとえば新しい顧客を受け入れる可能性のあるエンドポイントが新しい注文を受け入れることはできません。

これは、私が非常に気に入らなければ、リソースを適切に識別することによって達成できます。

質問に直接お答えください。カスタムMIMEタイプの数をできるだけ少なくするようにしてください。 IMHOあなたはすでにここで言及されているように、それらのAPIを使用してさまざまなバージョンのAPIを宣言することができます。