REST APIを介して公開したいオブジェクト階層があり、ベストプラクティスについて説明したいと思います。この質問は以前に確認しました(例 ここで最後) 、 ここ 、 ここ 、特に ここ )ですが、実際に結論が出ることはありません。
Animal
と言う1つの基本クラスと、Antelope
、Bird
、...、Zebra
を継承するさまざまなクラスがあるとします。動物の種類ごとに固有の属性があります。
どちらが良いですか?
/animals
。体の種類によって多少送受信が異なります。解析に役立つtype
フィールドがあります。/animals/antelopes
、/animals/birds
、...、/animals/zebras
。各エンドポイントは常に一貫したボディを受け入れて返します(ただし、これらのボディは互いに異なります)。オプション#1を使用します。理由は:あなたのリスト-アンテロープ、バード、...、ゼブラが将来増加する場合はどうなりますか?動物ごとに個別のエンドポイントを作成することになります。
前提として、/animals/antelopes
のペイロードと/animals/birds
のペイロードには大きな違いはありません。違いが大きい場合は、ペイロードごとに個別のエンドポイントを作成する必要があります。
ペイロードにわずかな違いがある場合、キーと値のペアを含む追加のマップを追加することをお勧めします。これらのペアは、その特定の動物タイプに固有の値です。
あなたが述べたように、余分なマップはタイプであることができます-
{
'shared_animal_attribute_1': 'foo',
'shared_animal_attribute_n': 'bar',
'extra_attributes':
{
'antelopiness': 10
}
}
サーバー側でこれらの属性の処理ロジックを追加する必要があります。これにより、個別のエンドポイントを維持する手間が軽減されます。検証するスキーマがある場合、それは手間のかからない実装です。
OpenAPI 3.0(以前のSwagger)は、JSONのポリモーフィズムを真にサポートしています。
JSONスキーマv1.0以降、oneOf、allOf、anyOfなどのキーワードを使用してスキーマを組み合わせ、検証されたメッセージペイロードを取得することが可能になりました。
https://spacetelescope.github.io/understanding-json-schema/reference/combining.html
ただし、Swaggerのスキーマ構成は、キーワードdiscriminator(v2.0 +)およびoneOf(v3.0 +)継承とポリモーフィズムをサポートします。
https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaComposition
多形の例を提供しましたPOST method here 。