REST API 版本控制模式指南

Question

我正在编写庞大的 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 文档轻松发现它。

你的意见是什么？

Answer 1

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

REST 不关心您为资源标识符使用的拼写约定。

---

RFC 3986 定义了paths and path segments。

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

因此，许多人会选择将其标识符层次结构与其资源层次结构保持一致。这样做不是强制，但作为一个组织原则，它还不错，当然也不比任何其他任意选择的约定差。

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

/photos     <-- the collection
/photos/17  <-- an item in the collection

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

---

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

---

我认为一个很好的指导原则是：任何路径段都意味着在同一层次级别存在同级。 /membership/api 暗示了/membership/something-that-isnt-api 的存在——否则，为什么不只是/membership？