Question

我正在设计一些可在api.ourdomain.com/下访问的REST API 会有几个API 像

api.ourdomain.com/Provider/
api.ourdomain.com/Consumer/
api.ourdomain.com/Customer/
api.ourdomain.com/Authorization/

等这些不是资源而是非常独立的API，在我们的api子域下。

现在我的困惑是，

我应该继续，

api.ourdomain.com/Provider/v1/resource/etc/

或

 api.ourdomain.com/v1/Provider/resource/etc/

所以问题实际上是，在API的名称之后放置版本的位置

[/提供者/ V1 / XYZ /等]

或从组织角度来看，api类型提供商的v1

[/ V1 /提供者/ XYZ /等]

任何建议表示赞赏感谢。

Answer 1

据我所知，目前还没有任何惯例。以下是来自Google，Yahoo和Microsoft的API示例：

https://www.googleapis.com/language/translate/v2?parameters

http://local.yahooapis.com/MapsService/V1/geocode

http://dev.virtualearth.net/REST/v1/Locations/FR/postalCode/locality/

我的偏好是将版本一直保留在最后（例如Google）。这样，大多数URL保持不变，只有最后一部分被更改。同样，这只是我的偏好，而不是惯例。

Answer 2

这不能以一般方式回答，但我相信您的案例的答案可以由预期的客户端应用程序很好地确定，因为您处于受限环境中并且您知道API的业务案例。

例如，如果您的客户端应用程序需要跨“提供者”和“消费者”子域工作，我建议将该版本放在API根目录（$ SERVER / $ VERSION / $ SUBDOMAIN）中，因为每个子域都要进行版本控制分开没有多大意义。从客户端的角度来看，API充当单个实体。（在源代码中，你有一个常量“apiVersion”）。

如果每个端点将由不同的客户端应用程序使用（例如“Consumer”的移动应用程序和“Provider”的桌面客户端系统），我建议对子域名进行版本控制（$ SERVER / $ SUBDOMAIN / $ VERSION），因为不同的开发速度可以应用于各种系统，系统或多或少是独立的。

值得注意的是，第二种方法更灵活，可以映射到第一种方法：

$SERVER/1.0/$SUBDOMAIN_A/
$SERVER/1.0/$SUBDOMAIN_B/

可以轻松地重写为==＆gt;

$SERVER/$SUBDOMAIN_A/1.0
$SERVER/$SUBDOMAIN_B/1.0

我会采用第二种方法，只是为了更安全一点 - 即使您同时升级所有API，这也会有效。

遵循的一般规则是执行良好的API设计并尽最大努力避免不兼容的更改，这些更改会迫使您升级API版本。

更新：还有一件事 - API依赖的概念。例如，如果您升级API以进行身份验证以便需要新的API版本，则所有客户端也需要升级，您可能需要单独对此API进行版本控制。这是第二种方法的又一点......

希望有帮助...

在同一域下有多个api时，REST API的版本控制

2 个答案: