定义正确的 API 端点 REST/RPC

Question

我正在为 Invoice 实体开发一个微服务 API，该 API 接受输入采购订单项目（即 PO 项目）标识符s 的列表，例如。 PO# + productIdentifier 一起可以用来唯一标识一个 POItem。 API 的响应是 每个 PO 项目的发票d 数量。

输入模型 -

input GetInvoicedQuantityForPOItemsRequest {
    poItemIdentifierList : POItemIdentifierList
}

结构

list POItemIdentifierList {
    
 member : POItemIdentifier

}

structure POItemIdentifier {

   purchaseOrderNumber : String,

   productIdentifier : Long

}

POItem 的发票数量 = 从该 PO 项目创建的发票项目数量的总和。

注意：一个采购订单可用于创建多个发票。可以从多个 PO 创建发票。

我对 REST 很陌生，到目前为止，我们一直在旧服务中使用 RPC 端点。但现在我正在构建一个新服务，我在其中以 REST 格式定义端点（例如，CreateInvoice 已更改为 POST /invoice）并且 我需要一些来自 Stack Overflow 社区的建议，什么是定义此 API 的 REST 端点的正确方法，或者我们应该将其保留为 RPC 格式本身。

旧系统中此 API 的 RPC 端点：POST /getInvoicedQuantityForPOItems

我们对 REST 的第一次尝试是：POST /invoice/items/invoicedQuantityForPOItems。但是这个 URI 看起来不像是一个名词，它是一个动词。

Answer 1

这个 URI 看起来不像是一个名词，它是一个动词。

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

示例：此 URI 的工作方式与网络上所有其他 URI 的工作方式完全相同，即使“它看起来像一个动词”

• https://www.merriam-webster.com/dictionary/post

解释是，在 HTTP 中，请求的语义不是通过解析标识符来确定的，而是通过解析方法令牌（GET、POST、PUT 等）来确定的。 所以机器不关心标识符的拼写（除了纯粹的机械问题，比如确保它满足 RFC 3986 生产规则）。

URI 是资源的标识符。资源是文档的概括。因此，如果您的标识符看起来像文档的名称，而不是动作的名称，那么人们可能会更快乐。

棘手的地方：HTTP 是一种应用程序协议，其应用程序域是transfer of files over a network。 HTTP 中的方法是关于检索文档和元数据 (GET/HEAD) 或关于修改文档 (PATCH/POST/PUT)。 HTTP 中并不真正存在函数或参数化查询的概念。

通常的折衷方案是将参数作为文档的标识符的一部分，然后使用 GET 请求获取该文档的当前表示。在服务器上，您解析标识符以获得生成文档当前表示所需的参数。

所以这个标识符可能看起来像

/invoicedQuantityForPOItems?purchaseOrder=12345&productIdentifiers=567,890

嵌入在 URI 查询部分的键值对的 application/x-www-form-urlencoded 表示是 Web 上常见的拼写约定，主要是因为 HTML 表单与 GET 操作一起工作的方式。其他标识符约定当然可以工作，但如果您坚持使用URI template 轻松描述的约定，从长远来看，您可能会更快乐。