Question

目前，我们正在为我们的系统开发API，并且有些资源可能具有不同类型的标识符。例如，有一个名为orders的资源，它可能具有唯一的订单号，并且还具有唯一的ID。目前，我们只有ID的网址，即这些网址：

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。使用前缀

某些公共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确实：他们的网址以show.json结尾，因此您可以像以下一样使用它：

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

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

4。使用子资源

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

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

我喜欢这种方法的可读性，但我认为/api/orders/ordernumber/367652的含义是＆＃34;得到（只是）订单号367652＆＃34;而不是订单。最后，这打破了一些最佳实践，例如使用复数和仅使用真实资源。

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

Answer 1

对我而言，解决问题的最RESTful方法是使用方法2进行略微修改。

从理论的角度来看，您只需拥有有效的识别码来识别您的订单。在设计过程的这一点上，您的识别码是id还是订单号并不重要。它是唯一能够识别您订单的东西，而且还不够。

您在ids和数字格式之间存在歧义这一事实属于实施阶段，而不是设计阶段。

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

GET /api/orders/{some_identification_code}

这非常RESTful。

当然，您仍然存在解决模糊性的问题，因此我们可以继续执行实施阶段。不幸的是，您的订单identification_code集由两个共享格式的不同实体组成。它无法工作，这是微不足道的。但现在问题在于这些实体格式的定义。

我的建议非常简单：ID将是整数，而数字将是N1234567等代码。这种方法将使您的资源表示可以接受：

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

此外，它在许多情况下都很常见，例如快递货物。

Answer 2

我在同一个问题上苦苦挣扎，却没有找到完美的解决方案。我最终使用了这种格式：

GET /api/orders/{orderid}
GET /api/orders/bynumber/{orderNumber}

并不完美，但是可读。

Answer 3

我也在为此苦苦挣扎！就我而言，我真的只需要能够使用辅助ID进行GET，这使操作变得简单一些。

我倾向于使用ID的可选前缀：

GET /api/orders/{id}
GET /api/orders/id:{id}
GET /api/orders/number:{orderNumber}

否则这可能是使用URI规范path parameters的晦涩功能的一个机会，它使您可以将参数附加到特定的路径元素：

GET /api/orders/{id}
GET /api/orders/{id};id_type=id
GET /api/orders/{orderNumber};id_type=number

使用不合格ID的URL是规范的URL。非规范URL的行为有两种选择：返回实体，或重定向到规范URL。后者在理论上更纯净，但对用户而言可能不方便。或者对于知道的用户可能更有用！

解决此问题的另一种方法是将订单号建模为自己的东西：

GET /api/ordernumbers/{orderNumber}

这可能会返回一个仅带有ID的小对象，然后用户可以使用该对象来检索实体。甚至只是重定向到订单。

如果您还需要常规搜索资源，那么也可以在这里使用它：

GET /api/orders?number={orderNumber}

就我而言，我还不需要这样的资源，并且添加似乎只支持一个字段的通用搜索资源可能会令我不舒服。

Answer 4

这是我想到的另一种选择，我发现它更美味。

GET /api/orders/1234
GET /api/orders/1234?idType=id //optional
GET /api/orders/367652?idType=ordernumber

原因是它使路径保持与REST标准一致，然后在服务中，如果它们确实传递了idType = orderNumber（id的idType为默认值），则可以继续使用。

使用多个唯一ID

4 个答案: