REST API Accept json/pdf

Question

現在、APIを使用していますが、これはREST APIの実装が間違っていると思います。

あなたが最初に取得するときに我々は

1. GET V1/{organizationId} /請求書
2. GET V1/{organizationId} /請求書/ {GUID}

次のエンドポイントを持っています、すべてのインボイスが得られますが、Accept: Application/jsonヘッダーのない2番目のエンドポイントを取得した場合は、最初のエンドポイントからの応答が得られます。

APIを提供する会社は、場合、第2のエンドポイントは、両方のJSONを与えることができますし、PDFとして思われるPDF出力は、そのほかに

GET v1/{organizationId}/invoices/{guid}/pdf 

になるので、この理由はあると言います不正な形式の​​を送信すると、空白のページやエラーメッセージなどではなく、壊れたHTML 404エラーページが表示されます。

1. 2.エンドポイントが適切に処理され、それを要約すると？
2. PDFをJSON/XMLのような出力にすることはできますか？
3. 代わりに新しいエンドポイントにする必要はありませんか？
4. 不正なリクエストであっても、HTMLはエラー応答として許可されますか？

Answer 1

一部の人々は、「右」と「間違っている」RESTベースの質問を分類するために好きではないが、私はとにかく先に行きます：

1. はありません、2番目のリソースは常に表現を返す必要がありますつまり、請求書であり、請求書の集まりではありません。

2. はい、同じ「もの」の複数の表現を潜在的に返すことは完全にOKです。請求書はjsonとpdfの両方を返すことができ、「Accept」ヘッダーに基づいて正しいものを選択することができます。

3. いいえ、これらの「もの」は「エンドポイント」ではなくリソースなので、新しい「エンドポイント」であってはいけません。請求書はリソースであり、jsonドキュメントは単にリソースの「表現」です。

4. はい、エラー応答には、サーバーが送信しやすい表現であれば本文が含まれます。サーバーはもちろん、クライアントからの "Accept"ヘッダーを使用して自身の方向を決定する必要がありますが、そうする必要はありません。

いくつかの発言：これらのリソースはコレクションリソースからをリンクする必要があるので、それは、GETに間違っGUIDと請求書可能にすべきではありません。クライアントが（そうすべきである）リンクをたどると、間違ったguidを持つリンクをたどる方法がないはずです。

全く異なるリソース（請求書の代わりに請求書コレクション）を返すのは間違いですが、同じリソースを複数表現することは問題ありません。 「Accept」ヘッダーがない場合、サーバーは1つを選択するか、406 Not Acceptableを指定する必要があります。

1つの小さな点：mime-typeはapplication/jsonであってはなりません。これは、それが請求書であることをどのように知っているからですか？それは次のようなものでなければなりません：application/vnd.someprovider.invoice+json。最近誰かがmime-typesに悩まされていますが、私は完全性のためだけに言及します。