54

我们有一个域名为example.com. 现在我们想将此应用程序的一部分扩展为 REST API，并且我们正在讨论最佳 URL 模式。

我们可以使用 URL 模式api.example.com或example.com/api. 如果有的话，有哪些权衡需要考虑？

此外，关于 API 版本控制的方法有哪些权衡？它可以通过 URL ( v1.api.example.com,example.com/api/v1或一些奇怪的组合v1.example.com/api或api.example.com/v1) 来完成。或者，可以通过使用 HTTP 请求标头（或其他方式）来完成？

4

3 回答 3

20

这取决于您的需求。

如果您使用http://api.example.com它会使您的 API 成为子域。基本上，如果您的 REST 服务要由多个客户端使用，则此 URL 模式很好，但如果只有一个客户端连接到您的 API，则模式http://example.com/api/v1很好。但是，如果您想添加更多 API 并连接更多客户端，最好使用http://example.com/api/v1。例如，考虑以下内容。

http://example.com/reportapi/apioperation?parameters

http://example.com/paymentapi/apioperation?parameters

http://example.com/searchapi/apioperation?parameters

最后但同样重要的是，PayPal 使用模式http://example.com/api/v1。

于 2013-01-28T03:28:50.787 回答
5

我认为您应该考虑使用既不http://api.example.com也不http://example.com/api/v1。

相反，我建议使用http://example.com/api和内容协商进行版本控制。

以下是我的想法为什么：

使用子域：

根据URI Scheme Specification，您在 URI 的授权部分定义 API，用于定义您的主机，而不是在您的主机上定义应用程序或 API。您实际上是在为您的 API 创建一个不同的地址，这意味着身份验证可能不适用于 api.example.com，就像它对 example.com 一样。

这样做的一个正当理由可能是在为移动设备设计一个新实例时，例如 mobile.example.com，但我认为这更像是一个基础设施决策，而不是功能决策。

在主域上使用未版本控制的路径：

这里有两点信息：一是表示存在 API 资源，二是表示存在该 API 资源的版本号 (v1)。

用来/api/区分 API 和可能在/web/. 这可以被认为是常见的最佳实践。

我不确定您是否打算这样做，但您的问题包括有关如何解决 API 版本控制的查询。就个人而言，我认为 API 版本控制不应该使用 URL 来完成，因为它们旨在尽可能长时间地保持稳定。酷 URI 不会改变！相反，请考虑使用 HTTP Content-Type 信息来对您的 API 进行版本控制。我实际上在VMware 文档中发现了这种方法。此外，这里有一篇相当古老但仍然有用的关于内容类型版本控制的帖子，作者Peter Williams。

于 2013-10-06T13:42:59.043 回答
-1

这是一个权衡的案例，没有单一的最佳解决方案。

例如，如果您的http://example.com/通过标准 Web 界面和 API 提供内容，那么您需要类似的东西http://api.example.com/api/<version>/<the usual resource pattern> 来将基于浏览器的应用程序访问与 API 交互分开。这有意义吗？

示例：api.rottentomatoes.com

但是，即使您的域专用于 API 调用，无论如何使用上述模式也是有意义的，并保留http://example.com/用于与您的应用程序交互的其他方式。例如，您可能需要http://example.com/mobile/等。

于 2013-01-28T06:23:13.670 回答