如何为每个帐户设置多个“公司”的SaaS设计REST API

Question

我目前正在为公司开发SaaS，以管理他们的业务数据（员工，发票，订单，产品......）。目前的API设计如下：

GET /employees?limit=10&offset=0

GET /employees/ID

POST /employees

等等，适用于所有型号。此外，您可以使用查询参数应用更多过滤器。

到目前为止，我检查了登录帐户所属的公司。但是现在我希望帐户可以成为多个组织中的“成员”。例如。如果使用该平台的公司雇用“专家”，他们应该能够授予他的帐户访问权限（使他成为会员）。

问题：我应该如何在API设计中实现这一点？我想出了三个解决方案，但不知道哪个是最佳实践。

解决方案1：

GET /ORGANISATION-ID/employees?limit=10&offset=0

解决方案2：

GET /employees?limit=10&offset=0&organidationId=ORGANISATION-ID

解决方案3：

URI保持不变，但设置了标头：

|----------------|------------------------|
| Header name    | Value                  |
|----------------|------------------------|
| Authentication | Bearer TOKEN           |
| Organisation   | ID     ORGANISATION-ID |
|     ...        |         ...            |
|----------------|------------------------|

注意：始终设置Authentication标头。

我个人认为3号解决方案最优雅，但我不确定是否使用标题是不合适的。我认为解决方案2令人困惑，解决方案1会导致所有端点都以组织ID开头，这不是很好。

Answer 1

通常，我发现在API中的每个路径处理此问题的最佳方法是表示单个资源。

对我来说，这意味着，在您的情况下，一切都应该在组织下命名：

https://api.example.org/org/[orgid]/employees

这样，对于多个组织的成员来说，存在多个员工列表是非常明显的。

类似的公共示例可能是github。 github中的所有内容都是A）在用户下命名空间B）在组织下命名空间或C）是顶级github端点。