0

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

输入模型 -

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 社区的一些建议，什么是定义 REST 端点的正确方法这个 API 或者我们应该将它本身保存为 RPC 格式。

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

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

4

1 回答 1

1

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

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

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

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

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

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

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

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

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

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

于 2021-02-16T05:51:22.717 回答