REST 中的继承和多态性 API 建模

Question

我有一个 object 层次结构，我想通过 REST API 公开它，我想讨论最佳实践。我以前看过这个问题（例如here at the end, here, here, and especially here），但从来没有真正得出任何结论。

假设我有一个基础 class，比如 Animal，还有许多不同的 class 继承，比如 Antelope，Bird，.. ., Zebra。每种动物都有独特的属性。

哪个更好？

一个端点路径，/animals。根据种类的不同，您发送和接收的身体略有不同。有一个 type 字段可以帮助解析。
每种动物的单独端点路径，/animals/antelopes，/animals/birds，...，/animals/zebras。每个端点将始终接受并 return 一个一致的 body（但这些主体将彼此不同）。

Answer 1

我会选择选项 #1。原因是：如果你的列表 - Antelope, Bird, ..., Zebra 将来增加了怎么办？您最终将为每只动物创建单独的端点。

假设 /animals/antelopes 和 /animals/birds 的有效负载之间没有太大差异。如果差异更大，那么您将需要为每个有效负载创建单独的端点。

如果有效载荷之间存在微小差异，我建议添加额外的包含键值对的映射，这些键值对是特定动物类型的特定值。

正如您所提到的，extra map 可以是类型 -

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

您需要在服务器端对这些属性进行额外的处理逻辑。这将减少维护单独端点的痛苦。如果您有要验证的模式，它是一个无忧的实施。

Answer 2

OpenAPI 3.0（以前的 Swagger）在 JSON 中真正支持多态性。

自 JSON 模式 v1.0 以来，可以使用 oneOf、allOf、anyOf 等关键字组合模式并获得经过验证的消息负载。

但是，Swagger 中的模式组合已通过关键字 discriminator (v2.0+) 和 oneOf (v3.0 +) 支持继承和多态性。

我提供了一个多态 POST 方法的示例 here。

Inheritance and Polymorphism in REST API Modeling