最佳实践Restful API命名约定

Question

我们目前有一个大型的API，可为许多不同的客户端和应用提供服务。在继续前进的过程中，我们正在讨论将API端点拆分为专用端点。

我们的基本URL就是这样的api.domain.com/{apiVersion}

以此为例，我们为我们的主应用和经销商应用提供服务：

用户端点：api.domain.com/v1/users

代理商端点：api.domain.com/v1/resellers/sales

我们的想法是将其更改为：

api.domain.com/users

api.domain.com/resellers/sales

或进入：

users.domain.com

resellers.domain.com/sales

在这方面我没有找到任何好的最佳实践，因此也许有些人对此有一个有趣的链接或看法。

我的偏好设置为api.domain.com/...，因为所有内容都是API，您无需更改基本URL，但是第二个URL使其更专用恕我直言。

谢谢。

Answer 1

查看Roy Fielding on Versioning, Hypermedia, and REST可能会有用。

  

不幸的是，版本控制接口名称仅出于API所有者的目的管理更改。这是一种界面设计的近视视图：所有者对控制的渴望忽略了客户对连续性的需求。

     

....

     

总是有可能出于某些不可预料的原因而需要一个完全不同的API，尤其是在接口的语义更改或安全性问题要求放弃以前部署的软件时。我的观点是，无需使用版本ID就能预见到如此世界性的更改。 我们有该主机名。您创建的不是API的新版本，而是具有新品牌的新系统。

（强调）

您还可以查看Fielding的slides from Evolve '13