如何在Restful API中指定某些资源类型的亚型？

Question

（在 stackoverflow在REST API上的最佳实践上的博客和A subtypes上的问题讨论另一个角度。）

我们应该如何在REST API中指定相同资源类型的不同子类型？

例如，在CRM应用程序中考虑不同类型的联系人：B2C客户是个人，B2B客户的B2B客户以及B2E的人，这些人是我们自己公司的雇员。

我可以想到在URL路径中指定这两种方式。主要区别是它如何影响文档中必需的/可选资源属性列表。同样，这在处理API请求的代码中渗透。验证是否允许，必需或可选的某些属性之间可能有所不同。

在资源URL路径

https://api.example.com/contacts/b2b/:id
中，明确指定子类型。 https://api.example.com/contacts/b2c/:id
https://api.example.com/contacts/b2e/:id

或

https://api.example.com/b2b-contacts/:id < br> https://api.example.com/b2c-contacts/:id
https://api.example.com/b2e-contacts/:id \ \ \ \ \ \ \

优势是可以非常具体地定义API合同，并根据每种类型的资源量身定制。某些属性是常见的（ ID ， name ， street ，电子邮件 ...），而其他属性是特定的仅适用于一种类型（ coc ， duns ， vat-id ，...用于B2B联系人，雇员>雇员-ID ，<代码>部门， dob ，...适用于员工）。 API文档可以清楚地指定每个子类型/资源的允许/必需/可选属性列表。

（不要深入了解注册公司联系人或员工的正确方法...这只是一个示例。）

小组在URL路径中的公共资源下的不同子类型

https://api.example.com/contacts/ ：id
使用对象（资源状态表示符合其余条件）在要交换的属性之一中指定子类型。

这是更通用和灵活的，但是API文档需要清楚地指定每种联系类型所需的属性/可选的属性。 类型也将是一个属性。

，在这种情况下，该文档可能会列出

属性	适用于	所需
类型ID	的属性（或：B2B，B2C，B2E）	是否
name	ash	yesememair
yes email	全部	no no
Contact-type	是	因此
...	的	名称name 。
​	​	​
​	​	​
​	​	​
​	​	​
​	​	​
​	​	​
​	​	​
​	​	​
​	B2C	是的

（同样，不要批评这个CRM示例的细节和适当性。这只是一个例子。我知道我们不应该存储社会保险号，而B2B客户通常也包含/参考某人。）

问题是

什么处理此操作的常见方法是什么？如何记录它，如何处理属性验证（允许，必需，可选）？

Answer 1

啊，好的旧的API资源多态性...这是一个棘手的:-)

总的来说，我要说的是这个问题的答案取决于如何使用API​​。一个很好的测试是API的用户如何列出“联系人”。用户是否需要“列出所有联系人”？还是他们想“列出所有B2B联系人”，而不需要与B2E联系人列出B2B联系人的能力？

如果将它们隔离为单独的资源（例如 B2BContact ， b2econtact 等），则用户无法浏览所有（任何类型）的联系人。但是，如果将它们合并为单一类型（例如， get/contacts？filter = type：b2b 或类似的内容），它们仍然可以浏览联系人。

如果不同类型的联系人（B2B / B2E / B2C）在根本上都是真正不同的，则将它们组合成单个资源类型是错误的。目前，您有一些仅适用于特定类型的属性，但不是全部 - 但这就是今天 。随着时间的流逝，属性的数量将增加，您会对API启动但不再那么多的事情感到有意义的事情感到非常困惑，这对用户来说可能会令人沮丧。

在细节上...

如果您要将它们分为多种资源类型，我建议将它们视为简单的分开资源（ get/b2b-contacts/ ， get/b2c-contacts/等），而不是同一资源的单独类型（例如， get/contacts/b2b ）。这样，如果他们将来需要偏离另一个人，那么没有什么可以将资源绑在一起，因为“当API启动时，它们恰好是联系人”。

如果您将它们与类型字段相结合，以指示

1. 仅适用于特定类型的字段， 尝试将它们放入该类型数据的“容器”中。例如，传真仅适用于B2B类型联系人，因此（在此处使用TypeScript，如果不是您的果酱，则对不起）：

class Contact {
  id: string;
  type: 'b2b' | 'b2c' | 'b2e';
  // ...

  metadata: B2BContactMetadata | B2CContactMetadata | ...;
}

class B2BContactMetadata {
  fax: string;
}

// ...

2. 适用于适用于3种类型的2个字段。如果传真突然对于B2B和B2E而不是B2C是有意义的，则您只需将其添加到B2ECONTACTMETADATA：

class B2BContactMetadata {
  fax: string;
}

class B2EContactMetadata {
  fax: string;
}

3. 非常小心地将字段引入 Contact> Contact> Contact> Contact> Contact -Level。如果某事对当前和将来的所有联系真正至关重要，那么它属于该最高级别。如果恰好适用于您现在拥有的所有联系类型，但是对于新型类型来说，它没有意义，然后将其放在特定于类型的元数据区域（或其中之一）。

---

有关此主题的更多探索，API设计模式的第16章涵盖了API中的多态性（ https://livebook.manning.com/book/api-design-patterns/chapter-16 ）