宁静的API设计内容输出

Question

最终，在SO成员回答我所有问题的帮助下，我终于准备好了API输出。 谢谢你

但我想知道输出中的一件事。 当我调用URL来接收API内容时，会得到如下信息：

[
    {
    "data": [
    {
    "incidentReference": "R-20150405-887f93",
    "latitude": 48.259698,
    "longitude": 11.434679,
    "archived": false
    },
    (...)
    ]
    }
]

我读过“您不会讨厌的构建API”这本书，它是很多东西的绝佳资源。 但是我不认为我看到的输出是正确的。 我的意思是，命名空间是我想要的。 但是它不应该是这样吗？

{
        "data": [
        {
        "incidentReference": "R-20150405-887f93",
        "latitude": 48.259698,
        "longitude": 11.434679,
        "archived": false
        },
        (...)
        ]
 }

因此，整个事情不应该仅是JSON吗？ 在我的情况下，它另外在数组中返回。 这些工作的功能如下：

public function index()
{
    $incidents = Incident::all();

    if( ! $incidents) {
        return Response::json([
            'error' => [
                'message' => 'There are no incidents in the database.',
                'code' => 100
            ]
        ], 404);
    } else {
        return $this->respond([
            $this->respondWithCollection($incidents, new IncidentTransformer)
        ]);
    }
}



  public function respond($data, $headers = []) {
        return Response::json($data, $this->getStatusCode(), $headers);
    }



  protected function respondWithCollection($collection, $callback) {
        $resource = new Collection($collection, $callback);
        $rootScope = $this->fractal->createData($resource);
        return $rootScope->toArray();
    }

因此，是的，responseWithCollection返回一个数组，但这是在响应函数中处理的，该函数声明return Response::json因此，我希望在调用资源时有一个json输出。

这个可以吗？

Answer 1

下一个结构

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

当您有多余的字段（例如项目总数，页面数等）时，这是个好方法：

 {"data" : [{}, {}], "page":1, "total": 100} 

否则，最好使用简单的结构：

[{"incidentReference": "R-20150405-887f93", ...}, {...}]

我建议您避免使用任何深层嵌套的结构。

Answer 2

RESTful响应应该尽可能简单： 仅输出纯json数据。 因此，限制和偏移量不应包含在服务器响应中，因为此客户端已经知道该信息。 而且，如果您格式化响应，则必须连接要与您的可靠服务交互的所有设备/平台/系统。

服务器应该返回客户端不知道的额外信息，例如查询集合的一部分时的全部元素。 但我会为此使用标头。 这样，服务器仍然返回简单的json数组，它不仅可以由您的客户端处理，而且可以由许多其他设备/平台/应用程序处理。

我的意见：仅输出纯json并使用标头获取其他信息，例如以下示例：

api / incidents / index.php：

// sanitize $_GET array, then output
$total = $incidents->getTotal();
$output = json_encode($incidents->fetch($GET['LIMIT'], $_GET['OFFEST'])); // pure example, I don't know how your framework works

// output
header('HTTP/1.1 200 OK');
header('Content-Type: application/json');
header('Collection-Total: '.$total);
header('Content-Length: ' . strlen($output));
echo $output;

例如，使用jquery访问此资源的Web应用将如下所示：

var limit = 10;
var offset = 200;
$.ajax({
    type: 'GET',
    url:'http://mywebsite.com/api/incidents/',
    data: {
        'LIMIT': limit, 
        'OFFSET': offset
    },
    success: function(data, textStatus, request){
        console.log('Incidents received...');
        console.log(data);
        console.log('There is ' + request.xhr.getResponseHeader('Collection-Total') + ' incidents in total');
    },
});

我会避免嵌套结构，例如Roman说的那样。 RESTful资源需要具有自己的标识符（URI）。 它必须返回一个对象（项目）或对象数组（项目集合），如下所示：

api/incidents // returns an array of objects
api/incident/[id] // returns a unique object (incident), using incident id in the URI
api/incidentreference/[id] // return an unique object (incident reference), usign incident reference id in URI

由于所有元素（项目或集合）都有其自己的标识符（URI），因此这种方法还带来了有趣的缓存可能性。 如果使用URI，Web协议/平台/设备可能会缓存所有服务器结果并自动优化整个应用程序。

我还建议即使没有要输出的元素，您的服务也应返回200 OK响应。 404说找不到资源。 找到资源，但现在不包含任何元素。 稍后可能包含元素。 某些设备/浏览器/平台可能会不同地处理404 HTTP代码。 我可能错了，但是我的REST服务始终返回200 OK /空json数组，而且我从来没有遇到过问题。 访问不存在的资源（URL）将返回404。