json - 关于 "deepest"资源项的正确 RESTful 响应格式所需的建议

Question

我有一个关于设计以 JSON 格式返回和接受数据的 RESTful API 的“概念性”问题。

考虑以下请求和响应:

GET http://host/records/12345

{ "id":"12345", "address":{"street":"main street","number":5,"city":"springfield"}}

GET http://host/records/12345/address

{"street":"main street","number":5,"city":"springfield"}

GET http://host/records/12345/address/city

{"city":"springfield"}

OR

springfield (=not valid json)

我意识到第二个答案不是有效的 JSON 响应，所以我认为后者是我问题的正确答案。然而，以键/值的形式响应对我来说看起来是多余的，因为请求者在请求期间已经知道“键”。

更新计数相同:

当我想用另一个值更新我的 12345 记录的城市时，提交什么更正确:

PUT http://host/records/12345/address/city

{"city":"paris"}  <- content of body when submitting

OR

paris <- content of body when submitting (=not valid json)

我问的原因是因为一个人已经足够了

PUT http://host/records/12345/address

{"city":"paris"}   <- content of body when submitting

什么被认为是最合适的方法？

谢谢，

杰

Answer 1

REST API 通常处理资源，这些资源松散地转换为数据库中的对象或表。您的第一个 GET 示例并不表示您正在尝试获取“地址”类型的资源。如果你想向你的 API 添加额外的资源，例如“公司”，那么这个就不清楚了。并且应该有一种方法可以获取所有地址的列表。所以要获得 API 调用的所有地址，看起来像

GET http://host/records/address

[{"id":"12345", "street":"main street","number":5,"city":"springfield"},
{"id":"12346", "street":"foo street","number":1,"city":"alexandria"}]

要获得特定地址，它看起来像

GET http://host/records/address/12345

{"id":"12345", "street":"main street","number":5,"city":"springfield"}

该 id 是地址对象的一部分，我认为没有必要像您的示例中那样将其分解为父对象。然后，您可以使用该 ID 让您的 Web 服务知道需要更新的内容。所以你的更新看起来像这样。

PUT http://host/records/address

{"id":"12345", "street":"main street","number":5,"city":"paris"}

通常客户端会发送整个对象，而不仅仅是要更新的字段。