REST API 多个根 URL

Question

我有一个带有 RESTful API 的应用，其中包含两个主要包。

一个包通过简单的 CRUD 操作公开数据库模型。它的一般目的只是为另一个服务和前端应用程序提供一些基础数据。它有版本控制以避免更新时出现其他服务错误：/api/v{number}/

其他包表示具有繁重数据库查询的业务逻辑，以避免前端聊天行为。它仅由前端应用程序使用。没有版本控制。

两个包都使用相同的 ORM 模型和 DB。

此应用仅供内部使用，没有外部客户或用户。只是我们公司。

主要的麻烦是决定如何在 URL 中表示这些特征。有两种选择：

1.对两个包使用相同的 URL 根：

domain.com/api/v{number}/...

2。使用不同的 URL 根：

domain.com/api/v{number} 用于简单的 CRUD api

domain.com/views/ 用于业务逻辑接口

第一个选项。

• 优点：

  1. 我们的开发人员可以在没有数据库结构知识的情况下使用 API，只需 API 文档。
  2. 前端开发人员只记住名称，而不是位置。

• 缺点：

  1. 命名问题。同一实体具有不同的数据库/业务表示。它会导致丑陋的模棱两可的名字，比如 entity_infos、entity_details、entity_deep等
  2. 业务 API URL 中的永久 /v1/，因为没有版本控制。

第二个选项。

• 优点：

  1. 业务 API 没有 URL 版本控制。
  2. 没有命名问题。

• 缺点：

  1. 没有抽象。您知道何时使用单表或繁重的业务逻辑。
  2. 前端应用程序使用具有相同资源名称的不同 API 根。这可能会让人感到困惑，尤其是对于新开发者而言。

如您所见，一个人的优点就是另一个人的缺点。

我想听听经过充分论证的意见以及一些相关链接。 谢谢。

Answer 1

从降低风险的角度来看，选项 2 优于选项 1。

如您所知，前端开发人员永远不应该直接访问业务数据。如果您的 CRUD API 允许这样做，并且您的前端开发人员使用它，则可能会导致不可逆转的数据损坏以及对公司的严重声誉和财务损失

任何访问业务数据的东西都需要经过严格的开发和测试流程。这种测试不是由前端开发人员执行的（相信我——我知道）。因此，业务逻辑开发人员应该是唯一使用 CRUD API 的人。如果前端开发人员需要业务逻辑当前未提供的数据操作，则需要规划、开发和测试 API 中的新方法。

即使业务逻辑调用只是执行单个 CRUD API 调用，前端开发人员也不需要知道。他们感兴趣的只是他们请求或提交的数据将以正确的方式处理。如果数据库模式发生更改（例如，在数据库升级期间），只需更新一个 API，而不是让整个前端搜索 API 调用。如果您有引用最新版本的别名 latest，并且业务逻辑使用该别名而不是 v1 等，则可以更新 CRUD API 等，而无需重新编写业务逻辑 API。 Atlassian 为其应用程序开发的 REST API 使用此别名。 （查看here 了解此内容。查看'URI 结构' 部分）

将不同 URL 上的两个 API 分开清楚地表明它们针对不同的目标。不让前端开发人员知道 CRUD API URL 通过默默无闻带来了一定程度的数据安全性。他们不知道的东西不能咬他们。

你总是需要考虑未来。您说该应用程序仅供“内部”使用，但如果您的公司收购了一项新业务并开始使用 API 怎么办？您真的希望他们直接查看数据吗？如果 API 允许公共访问怎么办？您当然希望 Joe Bloggs 和他的脚本小子朋友直接在您的数据库中四处寻找。分离 URL 使这更容易实现，因为您可以阻止对 CRUD API 的访问，而不必担心是否有后门路由通过它