web-dev-qa-db-ja.com

REST APIモデリングでの継承と多態性

REST APIを介して公開したいオブジェクト階層があり、ベストプラクティスについて説明したいと思います。この質問は以前に確認しました(例 ここで最後)ここここ 、特に ここ )ですが、実際に結論が出ることはありません。

Animalと言う1つの基本クラスと、AntelopeBird、...、Zebraを継承するさまざまなクラスがあるとします。動物の種類ごとに固有の属性があります。

どちらが良いですか?

  1. 1つのエンドポイントパス、/animals。体の種類によって多少送受信が異なります。解析に役立つtypeフィールドがあります。
  2. 動物の種類ごとの個別のエンドポイントパス/animals/antelopes/animals/birds、...、/animals/zebras。各エンドポイントは常に一貫したボディを受け入れて返します(ただし、これらのボディは互いに異なります)。
10
emft

オプション#1を使用します。理由は:あなたのリスト-アンテロープ、バード、...、ゼブラが将来増加する場合はどうなりますか?動物ごとに個別のエンドポイントを作成することになります。

前提として、/animals/antelopesのペイロードと/animals/birdsのペイロードには大きな違いはありません。違いが大きい場合は、ペイロードごとに個別のエンドポイントを作成する必要があります。

ペイロードにわずかな違いがある場合、キーと値のペアを含む追加のマップを追加することをお勧めします。これらのペアは、その特定の動物タイプに固有の値です。

あなたが述べたように、余分なマップはタイプであることができます-

{
 'shared_animal_attribute_1': 'foo', 
 'shared_animal_attribute_n': 'bar', 
 'extra_attributes': 
     { 
         'antelopiness': 10
     }
}

サーバー側でこれらの属性の処理ロジックを追加する必要があります。これにより、個別のエンドポイントを維持する手間が軽減されます。検証するスキーマがある場合、それは手間のかからない実装です。

5
asg

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

2
dbaltor