RESTful API：使用路径参数还是查询参数

Question

首先，我知道路径参数需要在指向资源时使用，而查询参数则用于定义可以添加“属性”（或随时间变化）的内容。

然而，假设我需要获取属于某个用户的数据。

在这种情况下，我喜欢将REST API URL编写为以下格式。

https://mylink/user/getbyid

AND not

https://mylink/user/get

在我编写REST API时，我会像这样调用URL：/user/getbyid?id=1。而在我不编写API的情况下，您将调用/user/get/1。

由于我编写我的API调用方式为/user/getbyid、/user/getbyname、/user/getbyuid，因此我很少使用路径参数。99%的时间我使用查询参数。

考虑到我编写API调用的方式，我是否违反了最佳实践？或者我所做的是正确的还是可以忽略的？

- PeakGen

---

getbyid更像是RPC而不是REST。REST应该是GET /user/{id}。至于搜索，我见过使用POST /user，并带有一个包含筛选条件的JSON体，例如{"name": "the name"}。 - codebrane

Answer 1

我知道路径参数需要用于指向资源，而查询参数则用于定义可能添加“属性”（或随时间变化的内容）的内容。

实际上并不完全正确-您可以根据自己的喜好将信息编码到路径或查询中；只要您的标识符符合RFC 3986中定义的生产规则即可，机器就不会在意。

“资源标识符”包括路径和查询部分。

由于我编写API调用的方式为/user/getbyid，/user/getbyname，/user/getbyuid，因此我很少使用路径参数。99%的时间我都在使用查询参数。

没问题，这样做是可以的。

考虑到我编写API调用的方式，我是否违反了最佳实践？还是我的方法是正确的或可以忽略的？

可以忽略，资源标识符有点像变量名称；人们可能会花费数小时讨论变量名称，但机器并不关心。资源标识符也是如此。

这些标识符可以改进吗？我认为可以；关键思想是我们正在标识一个资源，而不是标识该资源的实现细节。标识符在某种意义上是“文档名称”。

删除getby...路径段也是可以的。

/users?id=1
/users?name=bob
/users?uuid=469149ae-ecc6-4652-b094-17c211ff58ef

......但是，根据您的路由实现方式，消除这三个资源之间的歧义可能会很麻烦。添加额外的路径段以使路由更容易是没问题的。

- VoiceOfUnreason

---

这是一个很好的解释！ - PeakGen

Answer 2

设计REST API执行基本的CRUD（创建，读取，更新，删除）操作的最佳实践是使用HTTP方法GET POST PUT PATCH DELETE、URL和/或参数的组合。

假设您想要设计一个REST API来执行用户的CRUD操作

1. 创建

要执行创建操作，请设计一个带有POST HTTP方法的端点/users。

# http method  URL parameters
POST https://<yourdomain>/users, { first_name: "Peak", last_name: "Gen"}

2. 读取

要执行读取，请设计一个带有GET http方法的端点/users/<id>。

# http method  URL parameters
GET https://<yourdomain>/users/1

2. 更新

为了执行更新，请设计一个带有PUT或PATCH HTTP方法的端点/users/<id>。

# http method  URL parameters
PUT https://<yourdomain>/users/1, { first_name: "Nitin", last_name: "Sri"}

2. 删除

要执行删除操作，请设计一个带有DELETE HTTP方法的端点/users/<id>。

# http method  URL parameters
DELETE https://<yourdomain>/users/1

如果你注意到了，读取、更新和删除使用相同的URL，但是它们的HTTP方法不同。这意味着相同的URL基于它们的HTTP方法路由到不同的操作。

了解REST API的更多信息。

- Nitin Srivastava