REST API建模中的继承和多态

Question

我有一个对象层次结构,我想通过REST API公开,我想讨论最佳实践.我之前已经看过这个问题(例如,最后,这里,这里,尤其是这里),但从未真正得出任何结论.

假设我有一个基类,说Animal,和继承,比如说很多不同类别Antelope,Bird..., Zebra.每种动物都有独特的属性.

哪个更好？

1. 一个端点路径,/animals.你根据种类发送和接收略有不同的身体.有一个type字段可以帮助解析.
2. 对于每一种动物的一个单独的端点路径,/animals/antelopes,/animals/birds,..., /animals/zebras.每个端点总是接受并返回一致的主体(但这些主体彼此不同).

Answer 1

我会选择＃1。原因是：如果您的清单-羚羊，鸟，...，斑马线将来增加了怎么办？您将最终为每只动物创建单独的端点。

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

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

正如您所提到的，多余的地图可以是-

{
 '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 等关键字组合模式并获得验证的消息有效负载。

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方法的例子在这里。