Question

我终于准备好了我的API输出，并得到了SO成员的一些帮助，回答了我的所有问题。谢谢顺便说一句。

但我想知道我的输出中有一件事。当我调用URL来接收API内容时，我会得到类似的结果：

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

我读过这本书＆＃34;构建你赢得并不厌恶的API＃34;对很多东西来说，这是一个很好的资源。但我不认为，我看到的输出是正确的。我的意思是，命名空间是我想要的。但它不应该是这样的吗？

{
        "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();
    }

所以是的，respondWithCollection返回一个数组，但这是在响应函数中处理的，它指出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');
    },
});

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

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说没有找到资源。找到了ressource，但现在不包含任何元素。它可能稍后包含元素。某些设备/ broswers /平台可能会以不同方式处理404 HTTP代码。我可能错了，但我的REST服务总是返回200 OK /空json数组，我从来没有遇到过问题。访问不存在的资源（url）将返回404。

Restful API设计内容输出

2 个答案: