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

时间:2012-03-22 23:28:23

标签: api rest version

我正在设计一些可在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 /等]

任何建议表示赞赏 感谢。

2 个答案:

答案 0 :(得分:0)

据我所知,目前还没有任何惯例。以下是来自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保持不变,只有最后一部分被更改。同样,这只是我的偏好,而不是惯例。

答案 1 :(得分:0)

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

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

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

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

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

可以轻松地重写为==>

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

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

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

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

希望有帮助...