REST 合并了所有记录和一条记录

Question

我正在构建具有发票的 REST 端点。我需要在 3 个级别的描述中构建所有发票的列表（默认为详细，仅汇总，一个包含客户信息）。

我还需要为包含更多信息的单个发票构建端点。

我在想

GET /invoices               <-- detailed
GET /invoices?mode=sums     <-- sums
GET /invoices?mode=customer <-- sums
GET /invoices/TNTV002793849 <-- individual invoice

但我看到其他人可能实现了两个不同的

GET /invoices/detailed     <-- detailed
GET /invoices/sums         <-- sums
GET /invoices/customer     <-- sums
GET /invoice/TNTV002793849 <-- individual

我已经从阅读中知道所有这些都可以算作 REST，如果有什么我需要制作一个带有链接的 HATEOAS，我没有真正的理由需要它。

我的问题更多是从实践的角度出发，例如哪个更容易实施、更安全、更常见。

我可能会将 python 与 Flask 一起用于服务器，如果重要的话，我编写的一个客户端将是 JQuery。

Answer 1

正如您自己所说，这并不重要。所以下面主要是个人意见。

使用 /invoice/TNTV002793849 和 /invoices/ 的警告是同一概念有 2 个不同的命名空间。我认为这有点不寻常和出乎意料。很高兴能够删除 url 的最后一部分并获得一个合乎逻辑的父级。

所以我会选择使用相同的顶级命名空间。我个人也会使用 'singular' 代替复数形式，但这也只是一个温和的偏好。

接下来的问题是，如果所有内容都使用 'invoices' 前缀，那么您是否应该同时拥有 /sums 和 /TNTV002793849。最大的问题是，会不会发生碰撞？你能有一张名为 sums 的发票吗？如果这是真的，那就很难了。

如果 ?mode=sums 和 ?mode=customer 模式与父 /invoices 的数据非常相同，您可能还想使用内容协商。如果它们截然不同，那么我会觉得 ?mode= 不太合适，并且只会有完全独立的端点。

所以所有这些加在一起，会引导我：

GET /invoice               <-- full list of invoices
GET /invoice/{id}          <-- a specific invoice
GET /invoice-summary       <-- Some report
GET /customer/{id}/invoice <-- All invoices for a specific customer

我不知道所有这些猜测都特别适用于您，但我希望这里的内容足以让您对自己的决定充满信心。

REST 合并了所有记录和一条记录

REST combined all records and one record

rest

url-design