WebAPI PUT/POST 中的部分实体更新 [英] Partial Entity Updates in WebAPI PUT/POST

问题描述

假设您有一个存储库方法来更新文档:

Say you have a repository method to update a Document:

public Document UpdateDocument(Document document)
  {
  Document serverDocument = _db.Documents.Find(document.Id);
  serverDocument.Title = document.Title;
  serverDocument.Content = document.Content;
  _db.SaveChanges();
  return serverDocument;
  }

在这种情况下，实体有两个属性.更新 Document 时，JSON 请求中需要这两个属性，因此请求 PUT/api/folder 的主体为

In this case, the entity has two properties. When updating a Document, both of these properties are required in the JSON request, so a request to PUT /api/folder with a body of

{
  "documentId" = "1",
  "title" = "Updated Title"
}

将返回错误，因为未提供内容".我这样做的原因是，即使对于可为空的属性和用户未更新的属性，强制客户端在请求中指定这些字段以避免用空值服务器端覆盖未指定的字段似乎更安全.

would return an error because "content" was not provided. The reason I'm doing this is because, even for nullable properties and properties that the user doesn't update, it seems safer to force the client to specify these fields in the request to avoid overwriting unspecified fields with nulls serverside.

这导致我在 PUT 和 POST 请求中始终要求每个可更新的属性，即使这意味着为这些属性指定 null.

这很酷吗，或者是否有一种模式/实践我还没有了解，可以通过仅通过网络发送所需的内容来促进部分更新?

Is this cool, or is there a pattern/practice that I haven't learned about yet that might facilitate partial updates by sending only what is needed over the wire?

推荐答案

API 设计的最佳实践是使用 HTTP PATCH 进行部分更新.事实上，像您这样的用例正是 IETF 最初引入它的原因.

The best practice in API design is to use HTTP PATCH for partial updates. In fact, use cases like yours are the very reason why IETF introduced it in the first place.

RFC 5789 对其进行了非常精确的定义:

RFC 5789 defines it very precisely:

PATCH 用于对资源应用部分修改.

需要一种新方法来提高互操作性并防止
错误.PUT 方法已经定义为覆盖资源
具有完整的新主体，并且不能重复使用以进行部分更改.否则，代理和缓存，甚至客户端和服务器，都可能获得
对手术结果一头雾水.POST 已经被使用但是没有广泛的互操作性(一方面，没有标准的方法来
发现补丁格式支持).

A new method is necessary to improve interoperability and prevent
errors. The PUT method is already defined to overwrite a resource
with a complete new body, and cannot be reused to do partial changes. Otherwise, proxies and caches, and even clients and servers, may get
confused as to the result of the operation. POST is already used but without broad interoperability (for one, there is no standard way to
discover patch format support).

Mark Nottingham 写了一篇关于在 API 设计中使用 PATCH 的很棒的文章 - http://www.mnot.net/blog/2012/09/05/patch

Mark Nottingham has written a great article about the use of PATCH in API design - http://www.mnot.net/blog/2012/09/05/patch

在你的情况下，那将是:

In your case, that would be:

  [AcceptVerbs("PATCH")]
  public Document PatchDocument(Document document)
  {
      Document serverDocument = _db.Documents.Find(document.Id);
      serverDocument.Title = document.Title;
      serverDocument.Content = document.Content;
      _db.SaveChanges();
      return serverDocument;
  }

这篇关于WebAPI PUT/POST 中的部分实体更新的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！