エンドポイント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は、実際には「大」および「小」という用語を使用していません。ここでは、これらが同じオブジェクトの異なるフィールドセットであることを示すために使用しています。
このエンドポイント:
api\Items
これと同じではありません:
api\Items\1
したがって、異なる応答を返す可能性があります。あなたが示したように、IDでアイテムを取得するとより重いオブジェクトが返される可能性がありますが、アイテムを取得するとプロパティがいくつかあるリストが返される場合があります。エンドポイントがそのように命名されている場合、api /エンドポイントで「小さい」や「大きい」などの説明的な用語は避けてください。
また、エンドポイントにバージョンを配置することもお勧めします。結論として、APIが単純であるほど、他の人が使いやすくなります。