用于更新地图的REST API是否应允许将地图设置为空? [英] Should REST APIs for updating a map allow setting the map to empty?

问题描述

我有一个rest API，用于管理键到值的简单映射.

I have a rest API for managing a simple map of keys to values.

例如，GET请求可能返回以下内容:

For example, the GET request could return the following:

 {
    "keyA": "valueA",
    "keyB": "valueB"
 }

在请求正文中有一个PUT端点用新映射替换该映射.例如，可以将地图替换为新地图:

There is a PUT endpoint that replaces the map with a new map in the body of the request. For example, the map can be replaced with a new map:

 {
    "keyC": "valueC"
 }

这将删除键"keyA"和"keyB"，并添加"keyC".我们正在讨论的问题是，是否应允许PUT请求发送一个空的映射{}，以完全清除该映射，使它没有键.这应该被阻止吗?这是否遵循REST约定?

This removes keys "keyA", and "keyB", and adds "keyC". The question that we are debating is whether or not the PUT request should be allowed to send an empty map {} to clear out the map altogether so it has no keys left. Should this be blocked? Does any of this follow REST conventions?

推荐答案

这不是针对REST的问题，而是实际上将HTTP作为遵循REST体系结构方法的应用程序使用的默认传输协议.根据 RFC 7231 4.3.4 服务器

This is less a question targeted towards REST then it is actually targeting HTTP as the default transport protocol used by applications following a REST architecture approach. According to RFC 7231 4.3.4 a server

应该验证PUT表示是否与服务器对目标资源的任何约束一致，这些约束不能由PUT更改，也不会由PUT更改.

SHOULD verify that the PUT representation is consistent with any constraints the server has for the target resource that cannot or will not be changed by the PUT.

...

当PUT表示与目标资源不一致时，源服务器应通过转换表示或更改资源配置来使其一致，或使用包含足够信息的适当错误消息进行响应，以解释为什么该表示不适合

When a PUT representation is inconsistent with the target resource, the origin server SHOULD either make them consistent, by transforming the representation or changing the resource configuration, or respond with an appropriate error message containing sufficient information to explain why the representation is unsuitable.

我承认这有点含糊不清，并留下了很多解释的空间，但是我觉得是否要让一个空的主体成为资源的有效状态取决于您.如果您认为不应允许空主体，则只需返回409 Conflict响应，指示请求失败的原因即可.

I admit that this is a bit vague and leaves plenty of room for interpretation but I feel that it's more or less up to you whether you want an empty body being a valid state of the resource or not. In case you think it shouldn't allow an empty body simply return a 409 Conflict response indicating why the request failed.

需要在此处添加更多说明:REST将重点放在媒体类型的使用上.媒体类型是构成有效文档的元素的句法和语义描述.如果您将其与HTML进行比较，即会注意到它定义了何时可以将某些元素有效地放入文档中以及要使用哪种语法结构.对于此处的几乎所有文档，都应执行相同的操作.因此，媒体类型定义了对某些元素的约束，而没有约束.此处的PUT请求应针对在媒体类型中定义的约束条件来验证接收到的有效负载，以确定是否出现冲突或该表示形式是否可以转换为其他媒体类型格式.

A further note needs to be added here: REST puts focus on the usage of media types. A media type is a syntactical and semantical description of the elements forming a valid document. If you compare that with HTML i.e. you will notice that it defines when certain elements are valid to be put into a document or not and which syntactial structure to use. The same should be done for almost any document here either. The media type therefore defines constraints on certain elements and what not. A PUT request here should validate the received payload against the constraints defined in a media type to determine whether a conflict arrose or the representation may be converted to an other media type format.

application/json是一种非常弱的媒体类型，因为它仅定义了语法结构.它甚至不支持指向其他文档的链接.有几个扩展名，例如 application/hal+json 定义了链接关系的语义，尽管这很可能会仍然没有定义所需元素的语义.

application/json is a very weak media type in terms of REST as it just defines the syntactical structure. It doesn't even support links to other documents to start with. There are a couple of extensions like application/hal+json that define the semantics on link relations though this will most likely still not define the semantics of elements you require.

这就是为什么菲尔丁提到了

This is exactly why Fielding mentioned that

REST API应该花费几乎所有的描述性精力来定义用于表示资源和驱动应用程序状态的媒体类型，或者为现有标准媒体定义扩展的关系名称和/或启用超文本的标记类型. (来源)

这篇关于用于更新地图的REST API是否应允许将地图设置为空?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！