定义正确的 API 端点 REST/RPC

Question

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

输入模型-

input GetInvoicedQuantityForPOItemsRequest {
    poItemIdentifierList : POItemIdentifierList
}

结构

list POItemIdentifierList {
    
 member : POItemIdentifier

}

structure POItemIdentifier {

   purchaseOrderNumber : String,

   productIdentifier : Long

}

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

this URI does not look like a Noun it is a Verb.

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.

很容易描述的约定，您可能会更快乐

定义正确的 API 端点 REST/RPC

Defining right API endpoint REST/RPC

microservices

domain-driven-design

invoice

purchase-order