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"}

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