RESTful端点的输入DTO是否应与输出DTO匹配？

Question

我正在开发一个RESTful API,我在为API提供输入的过程中遇到了一些麻烦.

假设我有一个可以像这样获取的"Person"资源:api/person/{id}并返回如下对象:

public class Person
{
    public int Id { get; set; }
    public string Surname { get; set; }
    public string GivenName { get; set; }
    public DateTime DateOfBirth { get; set; }
}

如果我想更新那个人,API应该期待一个完整的Person实例,还是可以使用单独的DTO？

比如说,DateOfBirth不能改变,接受它作为输入是否被认为是RESTful:

public class UpdatePersonDto
{
    public string Surname { get; set; }
    public string GivenName { get; set; }
}

这意味着我将不得不为此端点api/person/{id}恢复Person使用时GET,而作为输入接收UpdatePersonDto使用时PUT.这对我来说听起来不对,但我不确定我是不是只是偏执狂.

所以我想我的问题总结为:接受给定资源端点上的数据结构是否适合与端点返回的数据结构不同？

Answer 1

REST 共识似乎是，当使用 PUT 进行更新时，提供整个实体进行替换。

以编程方式来说，让 PUT /person/{id} 接受在幕后映射到 UpdatePersonDTO 而不是 Person 的输入是可行的。

唯一的“问题”可能是它确实违背了普遍预期。

中间解决方案可以是 POST（或 PUT）/person/{id}/mutables，它可以接受 UpdatePersonDTO。

编辑：或者更明显的是： PUT /person/{id}/name 接受包含两个字段的 PersonName 参数。