json - 用于有限无序集合的 RESTful 设计的映射或数组？

Question

我和一位同事正在就 REST 服务的设计进行激烈的辩论。对于我们的大多数 API，对集合的 GET 调用返回如下内容:

GET /resource
[
    { "id": 1, ... },
    { "id": 2, ... },
    { "id": 3, ... },
    ...
]

我们现在必须实现对标识属性为“name”(而不是上面示例中的“id”)的属性集合的调用。此外，存在一组有限的属性，并且它们的发送顺序无关紧要。我想出的规范看起来像这样:

GET /properties
[
    { "name": "{PROPERTY_NAME}", "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
    { "name": "{PROPERTY_NAME}", "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
    { "name": "{PROPERTY_NAME}", "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
    ...
]

我的同事认为它应该是一张 map :

GET /properties
{
    "{PROPERTY_NAME}": { "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
    "{PROPERTY_NAME}": { "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
    "{PROPERTY_NAME}": { "value": "{PROPERTY_VALUE}", "description": "{PROPERTY_DESCRIPTION}" },
    ...
}

我引用与 API 其余部分的一致性作为按照我的方式格式化响应集合的原因，而他引用这个特定集合是有限的，顺序无关紧要。我的问题是，哪种设计最符合 RESTful 设计，为什么？

Answer 1

IIRC 如何返回资源的属性在 RESTful 方法中无关紧要。

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

从 API 客户端的角度来看，我更喜欢您的解决方案，因为它明确指出属性的名称是 XYZ。

而您的同事解决方案将暗示它是名称，但我如何确定(不阅读 API 文档)。尽量不要对您的消费客户进行任何假设，仅仅因为您知道它的含义(并且可能很容易假设它的含义)对于您的客户来说可能并不那么明显。

最重要的是，如果您决定将该值从名称恢复为 ID，它可能会破坏消费客户端。在这种情况下，您过去已经完成了。现在所有客户端都需要更改他们的代码，而他们不必在您的解决方案中进行更改，除非他们需要新添加的 id(或某些其他属性)。