1

我们正在开发一个 REST API，并且我们允许所有四个标准动词。在 POST/PUT 的情况下，API 客户端将需要修改某些字段的值。以伪示例为例：

class Employee {
  long Id;
  long DepartmentId; // should i expose this?
  string Department; // or should i expose this?
}
  • 这里的用例是客户端将发布一个新员工并填写所有字段。
  • API后面我们的数据库中有一个部门表
  • 客户将需要获取有效部门列表以发送
  • 客户端可以调用 API 来获取部门列表，如下所示：

{“department_id”：“1”，“department”：“技术”}，
{“department_id”：“2”，“department”：“人力资源”}

客户可以包括上述有效部门之一。我的问题是，POST/PUT 请求是否应该包含部门 ID 或名称？id 似乎更容易验证，但对客户来说不太“友好”。无论哪种情况，我们都可以根据我们的参考表正确验证，但我想知道最佳实践是什么。

4

3 回答 3

1

它应该使用 ID。API 使用者必须能够理解引用。在这种情况下，它需要理解它是指一个特定的部门。为此，客户端可能必须首先查询可用部门的列表，但只要您确实公开了这样的端点，您就不必担心。

使用部门名称会使部门名称成为唯一键，这会极大地改变语义。此外，您可能需要索引部门名称以有效地实现这一点，这是使用该名称的另一个有点严重的缺点。

于 2013-10-15T15:31:08.420 回答
0 
class Employee {
  long Id;
  Department Dept;
}

或者

class Employee {
      long Id;
      long DepartmentId;
    }

    class Department{
      long DepartmentId; 
      string DepartmentName; 
    }

这对于类结构来说更清晰。至于客户，他们将需要一个选择控件来选择部门——你不能指望他们知道 ID 或获得正确的名称。我用一个AutoComplete框来选择大的选择，或者用一个dropdown框来做一个小的列表。

要回答关于将什么发回from客户的问题，我会发回ID.

于 2013-10-15T15:35:48.333 回答
0

拥有传达含义的 URI 通常是更好的做法。例如

www.mylocalpaper.com/news/local/politics/2013_town_budget_approved

好于

www.mylocalpaper.com/sections/12/subsection/13/article/45

因为第 12 节第 13 小节第 45 条对 Web 服务器代码之外的任何人都没有任何意义。显然要确保每个部门的 URL 是唯一的（URL 中的 U）。

您还应该向客户端返回部门的完整 URL，而不仅仅是一个短名称，并使用该 URL 将用户添加到该部门。所以返回

{ "add_employee_url": "/departments/tech/employees/", "name": "Technology" },
{ "add_employee_url": "/departments/hr/employees/", "name": "Human Resources" }

然后客户端只需将员工详细信息发布到与选择匹配的 URL。客户用户选择“技术”，客户发布到/departments/tech/employees/.

如果部门的 URL 发生变化（比如说tech变成technology下线），客户端不会在意，因为它正在获取操作的完整 URL。

于 2013-10-15T16:42:31.913 回答