REST集合API：返回URL列表或对象列表

Question

我正在设计REST API，显然有集合。我见过两种不同的设计：

一种是将href的列表返回给各个资源：

{
  'list':
     [
    'http://xxxx',
    'http://xxxx',
    'http://xxxx'
     ]
}

另一种方法是在响应中包含所有单个对象：

[
  {
     foo: bar
  }
  {
     bar: foo
  }
]

每种方法的优点和缺点是什么？

Answer 1

我想说一个URL列表很少有用。我经常看到使用的模式更像这样：

{
  "data": [
    {…},
    {…}
  ]
}

这允许您作为开发人员提供有关整个集合的上下文。 JSON API和JSON-LD规范充分利用了这一点。如果您试图完全遵守HATEOS，它还允许将链接和分页信息直接嵌入到响应中。

第二个响应更多是惯用的JavaScript / JSON。它失去了具有对象上下文信息的能力，但是该信息也可以放在响应头中。您的API客户端也可以更容易地进行摘要，并且可以轻松地与其他API互操作。

另一个非常有趣的方法是Line Delimited JSON，看起来更像是这样：

{ "foo": "bar" }
{ "bar": "foo" }
{ "bax": "bux" }
{ "buz": "bax" }