rest api 子类型接口

Question

我在为管理员设计 restful url 结构时遇到了一些问题。在管理员中我有 "users" 但用户也有子类型 - 例如：内部员工、客户经理、客户员工 - 这些用户中的每一个都有特定的属性。对于创建新用户的场景，只需 POST /users 并包含一个属性 "type" 就可以很容易地说明它是什么类型的用户。但是，在记录此端点时，此解决方案似乎不太正确。每种用户类型都有不同的属性，只有该用户类型才需要这些属性，仅举几例：

内部人员：主管id、office id、各种内部标志
客户主管：部门id、公司id、通知偏好的各种标志
客户员工：部门编号、公司编号、地址、营业时间

虽然这些用户中的每一个都有一组共同的值，如用户名、密码、电子邮件，但感觉将它们都创建到同一个端点会在我们开始记录时造成混淆，因为不清楚哪些字段是必需的针对哪种用户类型（除非您查看代码）。我的另一个想法是为每个用户类型创建端点，例如：

POST /users/internal_staff
POST /users/client_supervisors
POST /users/client_staff

我很想听听处理过此类结构问题的人的意见，以及他们找到的最合理的解决方案。

Answer 1

您 POST /users 的方法完全正确。创建三个不同的端点就像在所有三种不同的方法中重复您的代码。

正如您明确提到的，当您对三种不同的员工子类型使用相同的端点时，您将需要处理文档。最好的选择是创建包含不同类型员工记录的枚举并发布它。作为文档的一部分，您需要提及员工类型的 可能值 。（例如，可以是 internal_staff_member、client_supervisor 或 client_staff）。

如果您收到任何不同类型的请求（上述值除外），您将需要抛出一个异常 'Invalid Employee Type. Employee type can be..'。

在文档中，您需要非常清楚地提及一些业务规则，说明哪些属性对于哪种类型的员工是强制性的。（例如，当员工类型是 - client staff，那么 - payload 必须包含以下属性：department id, company id, address ，营业时间。等）。

为了支持这些业务规则和验证，我们正在使用自定义注释（使用 java 和 spring）。

rest api 子类型接口

rest api interface for sub types

rest

api-design