Question

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

class Employee {
  long Id;
  long DepartmentId; // should i expose this?
  string Department; // or should i expose this?
}

此处的用例是客户将POST新员工并填写所有字段。
我们的数据库后面有一个部门表
客户需要获取要发送的有效部门列表
客户端可以进行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/。

如果部门的网址发生变化（比如说tech变为technology），客户端就不会关心，因为它正在获取该操作的完整网址。

REST API最佳实践

3 个答案: