RESTAPI建模中的继承和多态性

RESTAPI建模中的继承和多态性,rest,api,inheritance,polymorphism,api-design,Rest,Api,Inheritance,Polymorphism,Api Design,我有一个我想通过RESTAPI公开的对象层次结构,我想讨论一下最佳实践。我以前见过有人问过这个问题(例如,尤其是),但从来没有得出任何结论 假设我有一个基类,比如说Animal,还有许多不同的继承类,比如Antelope,Bird,…,Zebra。每种动物都有其独特的属性 哪个更好 一个端点路径,/animals。你发送和接收的尸体根据种类略有不同。有一个类型字段帮助解析 每种动物的独立端点路径,/动物/羚羊,/动物/鸟类,…,/动物/斑马。每个端点总是接受并返回一个一致的实体(但这些实体彼此不

我有一个我想通过RESTAPI公开的对象层次结构,我想讨论一下最佳实践。我以前见过有人问过这个问题(例如,尤其是),但从来没有得出任何结论

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

哪个更好

  • 一个端点路径,
    /animals
    。你发送和接收的尸体根据种类略有不同。有一个
    类型
    字段帮助解析
  • 每种动物的独立端点路径,
    /动物/羚羊
    /动物/鸟类
    ,…,
    /动物/斑马
    。每个端点总是接受并返回一个一致的实体(但这些实体彼此不同)
  • 我会选择选项1。原因是:如果你的名单-羚羊,鸟,…,斑马在未来增加怎么办?最终将为每个动物创建单独的端点

    假设
    /动物/羚羊
    /动物/鸟类
    的有效载荷之间没有太大差异。如果差异更大,则需要为每个负载创建单独的端点

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

    正如您所提到的,额外地图可以是-

    {
     'shared_animal_attribute_1': 'foo', 
     'shared_animal_attribute_n': 'bar', 
     'extra_attributes': 
         { 
             'antelopiness': 10
         }
    }
    
    您需要在服务器端添加这些属性的额外处理逻辑。这将减少维护独立端点的痛苦。 如果您有要验证的模式,那么它是一个无麻烦的实现。

    OpenAPI 3.0(以前的Swagger)真正支持JSON中的多态性

    自JSON schema v1.0以来,可以使用关键字(如oneOf、allOf、anyOf)组合模式,并获得经过验证的消息有效负载

    然而,Swagger中的模式组合已通过关键字鉴别器(v2.0+)和其中一个(v3.0+)得到增强,以支持继承和多态性


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

    Hm,@asg,我不确定每只动物的有效载荷和响应是如何相同的。事实上,它们是不同的——“根据种类,你发送和接收的身体略有不同”和“每种动物都有独特的属性”。我同意,如果每种动物都有相同的有效载荷和反应(1),这将是显而易见的选择。这里需要技巧的是它们是不同的。嘿@emft这就是你在问题2中提到的-#2-'每个端点的有效载荷和响应都是相同的'。如果是相同的,那么为什么需要一个单独的端点。。这就是重点。啊,我明白你的意思。我的意思是,如果每个动物都有一个端点,那么每个端点都会在端点内接收并返回一致的实体。也就是说,
    /animals/antelopes
    将始终具有身体A,
    /animals/birds
    将始终具有身体B,但身体A=/=身体B。我将进行编辑以反映这一点。好的。。知道了。问题是——主体A和主体B之间的差异有多大?有多少属性是不同的?如果这些值不高,您可以有一个包含键值对的额外映射,这些键值对是特定于特定动物类型的值。同样,这取决于这些额外属性是否可管理。如果没有,则可能需要创建单独的端点。但这应该是最后的选择。很有趣。你能再解释一下“额外的地图”是什么意思吗?类似于
    {'shared_animal_attribute_1':'foo',…,'shared_animal_attribute_n':'bar','extra_attributes':{'antelopity':10}}
    也许吧?OAS确实允许这样做。但是,不支持在Swagger UI()中显示该功能,我认为如果您不能向任何人显示该功能,则该功能的用途有限。@emft,不是真的。在编写此答案时,Swagger UI已经支持了这一点。而且服务器代码无法处理模式之一。OAS支持这一点,但看起来代码生成器不支持Java,OpenAPITools PR#5120似乎已经修复了它