定义正确的 API 端点 REST/RPC

如何解决定义正确的 API 端点 REST/RPC

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

输入模型 -

input GetInvoicedQuantityForPOItemsRequest {
    poItemIdentifierList : POItemIdentifierList
}

结构

list POItemIdentifierList {
    
 member : POItemIdentifier

}

structure POItemIdentifier {

   purchaSEOrderNumber : String,productIdentifier : Long

}

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

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

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

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

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

解决方法

这个 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 表示是网络上常见的拼写约定，主要是因为 HTML 表单就是这样处理 GET 操作的。其他标识符约定当然可以工作，但从长远来看，如果您坚持使用 URI template 易于描述的约定，您可能会更快乐。