REST API 版本控制模式指南

编程问答 2022-05-16

问题描述

我正在编写庞大的 Rest API，以使其易于发现，我正在以这种方式制作模式。

http://127.0.0.1:8000/membership/api/v1/make-a-payment

但我注意到人们过去常常以这种方式制作图案：http://127.0.0.1:8000/ap/v1/blabla

谁能告诉我最佳做法是什么？

这样写模式可以吗？ http://127.0.0.1:8000/membership/api/v1/make-a-payment ?

我只是想让 swegger 文档很容易发现它。

你有什么看法？

解决方法

谁能告诉我最佳做法是什么？

REST 不关心您对资源标识符使用什么拼写约定。

RFC 3986 定义了 paths and path segments。

路径组件包含数据，通常以分层形式组织...

因此，许多人会选择将他们的标识符层次结构与其资源层次结构对齐。这不是要求你这样做，但作为一个组织原则，它并不差，当然也不比任何其他任意选择的惯例差。

例如，一种常见的做法是，集合项的标识符拼写从属于集合本身的标识符。

{
    "manifest_version": 3,"name": "CustomUTM","version": "1.3","description": "Custom UTM Extension","declarative_net_request": {
    "rule_resources": [
      {
        "id": "ruleset_1","enabled": true,"path": "utmsource.json"
      },{
        "id": "ruleset_2","path": "utmmedium.json"
      },{
        "id": "ruleset_3","path": "utmcontent.json"
      },{
        "id": "ruleset_4","path": "utmcampaign.json"
      },{
        "id": "ruleset_5","path": "utmterm.json"
      }
    ]
  },"host_permissions": ["*://*/*"],"permissions": ["declarativeNetRequest","declarativeNetRequestFeedback"],"icons": {
          "128": "icon128.png" }
}

因此，您可能会合理地询问 api 是否是成员资格集合中多项中的一项，或者会员资格是否是 api 集合中多项中的一项。

您可能还想查看 relative resolution 以及如何使用点段在层次结构中向上导航。如果成员资格和其他想法之间的引用比 api 和其他想法之间的引用更常见，那么拼写 /api/membership 可能被证明是更方便的选择。

我认为一个很好的指导方针是：任何路径段都意味着在同一层级上存在兄弟姐妹。 /photos <-- the collection /photos/17 <-- an item in the collection 意味着 /membership/api 的存在——否则，为什么不只是 /membership/something-that-isnt-api ？

apiapiapi-versioningdjangodjangodjango-rest-frameworkrestrest