如何为每个帐户设计具有多个“公司”的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端点。