查询多个属性的正确REST表示法是什么

Question

有一个实体，

class Employee{
  int id;
  String name;
  String phoneNumber;
}

查询以下4种场景的正确REST-ful方式是什么：

1. 所有员工名单
2. 具有给定ID的员工
3. 具有给定ID和姓名的员工
4. 具有给定ID、姓名和电话号码的员工

两个起跑点非常直截了当：

1. /employee
2. /employee/{employee-id}

然而，现在我们想要根据多个属性筛选实体，我能想到的最佳解决方案是：

3. /employee/{employee-id}?name=abc
4. /employee/{employee-id}?name=abc&phoneNumber=123

有没有更好的方法来做到这一点？有些人提出了如下解决方案：

3. /employee/{employee-id}/{name}
4. /employee/{employee-id}/{name}/{phoneNumber}

然而，我觉得以上这些违背了宁静的表达方式。

Answer 1

按ID和姓名（以及电话号码）搜索员工有点矛盾。

通常，按ID查找员工不被视为搜索，而是对现有资源的引用（GET请求）。如果失败，应该返回HTTP 404。

按多个属性搜索通常是查询的POST，例如：

POST /employee/search HTTP/1.1

Name=Hasan&PhoneNumber=0612345678

混合按ID查找和按（多）属性搜索会引发一些问题：

• 是否只返回与所有属性匹配的结果

Answer 2

在RESTAPI中，必须将集合和特定资源分开。我会用复数形式指定一个集合，用单数形式指定资源。因此，集合中的特定资源可以通过/{collectionName}/{id}获取，如果要查询属性，请使用/{collectionName}？属性1=qwe

所以我宁愿这样构造它：

/employees                             # the entire collection of employees
/employees/{id}                        # a specific employee by id. No need to have any query params since we fetch an employee by its primary key.
/employees?name=abc&phoneNumber=123    # query the collection of employees for the ones having name=abc and phoneNumber=123