web-dev-qa-db-ja.com

代替のWeb APIエンドポイントから異なるデータ型を返すことはお勧めできませんか?

エンドポイントapi\LargeItemを備えたWeb APIを検討してください

LargeItemは、多くのプロパティと長い文字列を持つかなり大きなオブジェクトです。

ユーザーはGETのようにapi\LargeItem\1できます。これにより、ID1を持つLargeItemが返されます。

ただし、ユーザーが選択するためにこれらの項目のリストを入力する必要がある場合が多く、その場合、大きくリッチな水和オブジェクトは必要ありません。

一方では、ユーザーはapi\LargeItemを呼び出してそれらすべてを取得することを期待できますが、私はユーザーにそのようなリッチオブジェクトの大きなコレクションを使用するつもりはありません。彼らがリストを欲しがっているとき、私はむしろ彼らにSmallerVersionOfLargeItemを与えたいと思います。それは、例えば、IdとNameだけを持っているかもしれません。

異なるURLが含まれている場合、同じ名前のエンドポイントから異なる形状のオブジェクトを返すことができるかどうかについてのガイドラインまたは標準はありますか?

api\SmallerVersionOfLargeItems\のようなエンドポイントを持つことが望ましいですか?

[〜#〜] edit [〜#〜]これは、API呼び出しで?fieldsプロパティを使用しないことを除いて、JSON.NetのShouldSerializeの概念と同等です。

明確にするために:私のAPI apiは、実際には「大」および「小」という用語を使用していません。ここでは、これらが同じオブジェクトの異なるフィールドセットであることを示すために使用しています。

3
Matthew

このエンドポイント:

api\Items

これと同じではありません:

api\Items\1

したがって、異なる応答を返す可能性があります。あなたが示したように、IDでアイテムを取得するとより重いオブジェクトが返される可能性がありますが、アイテムを取得するとプロパティがいくつかあるリストが返される場合があります。エンドポイントがそのように命名されている場合、api /エンドポイントで「小さい」や「大きい」などの説明的な用語は避けてください。

また、エンドポイントにバージョンを配置することもお勧めします。結論として、APIが単純であるほど、他の人が使いやすくなります。

5
Jon Raynor