通过 RESTful API 中的 ID 或 slug 识别项目 [英] Identify item by either an ID or a slug in a RESTful API

问题描述

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

I'm currently designing an API and I came a cross a little problem: How should a URL of a RESTful API look like when you should be able to identify an item by either an ID or a slug?

我能想到三个选项:

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

这要求slug和ID是可区分的，在这种情况下不一定要给出.我想不出一个干净的解决方案来解决这个问题，除非你做这样的事情:

This requires that the slug and the ID are distinguishable, which is not necessarily given in this case. I can't think of a clean solution for this problem, except you do something like this:

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

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

This would work fine, however this is not the only place I want to identify items by either a slug or an ID and it would soon get very ugly when one wants to implement the same approach for the other actions. It's just not very extendable, which leads us to this approach:

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

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

This seems to be a good solution, but I don't know if it is what one would expect and thus it could lead to frustrating errors due to incorrect use. Also, it's not so easy - or let's say clean - to implement the routing for this one. However, it would be easily extendable and would look very similar to the method for getting multiple items:

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

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

But this has also a downside: What if someone wants to identify some of the items he want to fetch with IDs, but the others with a slug? Mixing these identifiers wouldn't be easy to achieve with this.

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

What is the best and most widely-accepted solution for these problems? In general, what matters while designing such an API?

推荐答案

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

Of the three I prefer the third option, it's not uncommon to see that syntax; e.g. parts of Twitter's API allow that syntax: https://dev.twitter.com/rest/reference/get/statuses/show/id

第四个选项是混合方法，您可以选择一种(例如 ID)作为单个项目的典型访问方法，但也允许基于 slug 进行查询.例如:

A fourth option is a hybrid approach, where you pick one (say, ID) as the typical access method for single items, but also allow queries based on the slug. E.g.:

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

您的路由很明显将/items/id 映射到/items?id=

Your routing will obvious map /items/id to /items?id=

可扩展到多个 id/slug，但仍满足将 URI 与底层数据模型匹配的 REST 范式.

Extensible to multiple ids/slugs, but still meets the REST paradigm of matching URIs to the underlying data model.

这篇关于通过 RESTful API 中的 ID 或 slug 识别项目的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！