json - 具有多个唯一 ID 的 Rest API 设计

Question

目前，我们正在为我们的系统开发一个 API，有些资源可能有不同种类的标识符。例如，有一个名为orders的资源，它可能有一个唯一的订单号，也有一个唯一的id。目前，我们只有 id 的 URL，即这些 URL:

GET /api/orders/{id}
PUT /api/orders/{id}
DELETE /api/orders/{id}

但现在我们还需要使用订单号的可能性，这通常会导致:

GET /api/orders/{orderNumber}
PUT /api/orders/{orderNumber}
DELETE /api/orders/{orderNumber}

显然这行不通，因为 id 和 orderNumber 都是数字。

我知道有一些类似的问题，但它们并没有帮助我解决问题，因为答案并不十分合适，或者他们的方法并不真正令人放松或易于理解(对于我们和可能使用 API 的开发人员而言)。此外，问题和答案部分超过 7 年。

举几个例子:

<强>1。使用查询参数

有人建议使用查询参数，例如

GET /api/orders/?orderNumber={orderNumber}

我觉得，有很多问题。首先，这是订单集合的过滤器，因此结果也应该是一个列表。但是，唯一订单号只有一个订单，这有点令人困惑。其次，我们使用这样的过滤器来搜索/过滤订单的子集。此外，查询参数是某种二等参数，但在这种情况下应该是一流的。如果对象不存在，这甚至是一个问题。通常 get 会返回 404(未找到)，但如果订单 1234 不存在，GET/api/orders/?orderNumber=1234 将是一个空数组。

<强>2。使用前缀

一些公共(public) API 使用某种鉴别器来区分不同的类型，例如喜欢:

GET /api/orders/id_1234
GET /api/orders/ordernumber_367652

这适用于他们的方法，因为 id_1234 和 ordernumber_367652 是他们真正的唯一标识符，也由其他资源返回。但是，这会导致像这样的响应对象:

{
  "id": "id_1234",
  "ordernumber": "ordernumber_367652"
  //...
}

这不是很干净，因为类型(id 或订单号)被建模了两次。除了更改所有标识符和响应对象的问题之外，如果您例如想要搜索所有大于 67363 的订单号(因此，也存在字符串/数字冲突)。如果响应没有添加类型作为前缀，用户必须为某些请求添加这个，这也会很困惑(有时你必须添加这个，有时不需要......)

<强>3。使用动词

这就是例如Twitter 可以:他们的 URL 以 show.json 结尾，因此您可以像这样使用它:

GET /api/orders/show.json?id=1234 
GET /api/orders/show.json?number=367652

我认为，这是最糟糕的解决方案，因为它不是 Restful 。此外，它还存在我在查询参数方法中提到的一些问题。

<强>4。使用子资源

有些人建议将其建模为子资源，例如:

GET /api/orders/1234 
GET /api/orders/id/1234   //optional
GET /api/orders/ordernumber/367652

我喜欢这种方法的可读性，但我认为 /api/orders/ordernumber/367652 的含义是“获取(仅)订单号 367652”，而不是订单。最后，这打破了一些最佳实践，例如使用复数且仅使用真实资源。

最后，我的问题是:我们是否遗漏了什么？还有其他方法吗，因为我认为这不是一个不寻常的问题？

Answer 1

对我来说，解决问题的最 RESTful 方法是使用方法 2 并稍作修改。

从理论上讲，您只需拥有有效的识别码即可识别您的订单。在设计过程的这一点上，您的识别码是 id 还是订单号并不重要。这是唯一标识您的订单的东西，这就足够了。

您在 ID 和数字格式之间存在歧义这一事实属于实现阶段的问题，而不是设计阶段的问题。

所以现在，我们拥有的是:

GET/api/orders/{some_identification_code}

这非常 RESTful。

当然你还有解决歧义的问题，所以我们可以继续执行阶段。不幸的是，您的订单 identification_code 集由两个共享格式的不同实体组成。这是微不足道的，它无法工作。但现在问题出在这些实体格式的定义上。

我的建议很简单:ids 是整数，而 numbers 是代码，比如 N1234567。这种方法将使您的资源表示可接受:

{
  "id": "1234",
  "ordernumber": "N367652"
  //...
}

此外，它在许多场景中都很常见，例如 express 。