通过 RESTful API 中的 ID 或 slug 识别项目

Posted 2023-02-19

【中文标题】通过 RESTful API 中的 ID 或 slug 识别项目

【英文标题】：Identify item by either an ID or a slug in a RESTful API

【发布时间】：2012-04-18 13:45:18

【问题描述】：

我目前正在设计一个 API，但遇到了一个小问题： 当您应该能够通过 ID 或 slug 识别项目时，RESTful API 的 URL 应该是什么样子？

我可以想到三个选项：

GET /items/<id>
GET /items/<slug>

这要求slug和ID是可区分的，本例中不一定给出。我想不出一个干净的解决方案来解决这个问题，除非你这样做：

GET /items/id/<id>
GET /items/slug/<slug>

这可以正常工作，但是这不是我想通过 slug 或 ID 来识别项目的唯一地方，当一个人想要为其他操作实施相同的方法时，它很快就会变得非常难看。它只是不太可扩展，这导致我们采用这种方法：

GET /items?id=<id>
GET /items?slug=<slug>

这似乎是一个很好的解决方案，但我不知道它是否是人们所期望的，因此它可能会由于使用不当而导致令人沮丧的错误。此外，为这个实现路由也不是那么容易 - 或者说干净 - 实现路由。但是，它很容易扩展，并且看起来非常类似于获取多个项目的方法：

GET /items?ids=<id:1>,<id:2>,<id:3>
GET /items?slugs=<slug:1>,<slug:2>,<slug:3>

但这也有一个缺点：如果有人想用 ID 识别他想获取的一些项目，而用 slug 识别其他项目怎么办？用这个来混合这些标识符并不容易。

对于这些问题，最好和最广为接受的解决方案是什么？ 一般来说，在设计这样的 API 时，什么是重要的？

【问题讨论】：

问题中的问题，什么是蛞蝓？

***说：“在 URL 中用于识别和描述资源的用户和 SEO 友好的短文本”或类似的东西。

根据该***文章和 Wordpress 词汇表 (codex.wordpress.org/Glossary#Slug) 中的示例，似乎 slug 是已经分层 url 的一部分。因此，在您的情况下，可能 items 用于 id，但 items// （例如）用于 slug。

我认为您也可以将其定义为用户友好的标识符。至少我是这个意思。

【参考方案1】：

在这三个选项中，我更喜欢第三个选项，这种语法并不少见；例如Twitter 的部分 API 允许使用这种语法： https://dev.twitter.com/rest/reference/get/statuses/show/id

第四个选项是混合方法，您可以选择一个（例如 ID）作为单个项目的典型访问方法，但也允许基于 slug 的查询。例如：

GET /items/<id>
GET /items?slug=<slug>
GET /items?id=<id>

您的路由显然会将 /items/id 映射到 /items?id=

可扩展至多个 id/slug，但仍符合将 URI 与底层数据模型匹配的 REST 范式。

【讨论】：

“将 URI 与底层数据模型匹配的 REST 范例。”是我担心的。但我想我会接受这个。

这几天几乎是可口可乐/百事可乐的问题。 :) 我会说您应该支持 /items/ 进行 RESTful 认证，但也允许基于 id 或 slug 搜索的查询字符串将在范式内。我更喜欢可乐。

因为我将有更多的查询参数来搜索所有返回数组的项目，所以在这里也返回一个数组是否明智？您可以搜索 slug，但无法通过它们清楚地识别项目，因此返回数组似乎是合乎逻辑的。

我将为GET /items/<id> 返回一个对象，但为所有查询参数返回一个数组，包括slug 并允许部分匹配。这是最有意义的，因为前端可以很容易地显示自动完成 slug 或名称的建议。 Slugs 和名称用于用户，ID 用于应用程序。

现在正在寻找类似的东西。我觉得在其中包含“搜索”的 URL 下提供部分匹配/数组返回选项可能更有意义，并且仅在仅使用对象名词时才具有直接资源映射。例如/items/search?slug= 返回匹配数组，/items?slug= 尝试直接匹配。