REST API 最佳实践

Question

我们正在开发一个 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_id": "2", “部门”：“人力资源” }

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

Answer 1

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

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

Answer 2

class Employee {
  long Id;
  Department Dept;
}

或

class Employee {
      long Id;
      long DepartmentId;
    }

    class Department{
      long DepartmentId; 
      string DepartmentName; 
    }

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

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

Answer 3

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

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

优于

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

因为第 12 节第 13 小节第 45 条对网络服务器代码之外的任何人都没有任何意义。显然要确保每个部门的 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。