1. 首页
  2. Laravel

LaravelJSON API简介

JSON API最初由Yehuda Katz于2013年5月起草,并于2015年5月达到稳定,其目的是使API调用高效。您可以根据需要获取数据,随着需求的变化添加或删除属性或关系。这使得进行API调用时所需的数据量和往返次数最小化。{json:api接口}
JSON API文档与任何其他API格式一样工作,您向端点发送请求并接收文档。jsonapi规范定义了资源的结构。此结构有助于规范化您使用API的方式。
例如,当您通过简单的GET请求调用资源articles时。
1GET /articles HTTP/1.12Accept: application/vnd.api+json
您收到的响应应该是这样的:
1// … 2{ 3\”type\”: \”articles\”, 4\”id\”: \”1\”, 5\”attributes\”: { 6\”title\”: \”Rails is Omakase\” 7}, 8\”relationships\”: { 9\”author\”: {10\”links\”: {11\”self\”: \”http://example.com/articles/1/relationships/author\”,12\”related\”: \”http://example.com/articles/1/author\”13},14\”data\”: {15\”type\”: \”people\”,16\”id\”: \”9\”17}18}19},20\”links\”: {21\”self\”: \”http://example.com/articles/1\”22}23} // …
似乎足够简单。作者关系包括与作者关系本身的一个链接和关于作者关系的一些基本信息。使用文档中的链接,您可以检索有关资源的信息。
但这只是表面现象。JSON API有许多特性,使其易于使用。复合文档
为了减少HTTP请求的数量,服务器可以允许响应包括相关资源和请求的主要资源。这种响应称为\”复合文档\”。
复合文档是一种包含包含关系数据的资源。例如,在请求一篇如前所示的文章时,它可能包含作者的数据,这样您就不需要第二次调用来获取文章的作者了。除非对特定端点进行了编程,否则获取要一次性使用的资源的完整数据是闻所未闻的。在服务器端,这样的请求很容易缓存和失效。
只要看一下这个返回一组1文档的示例。
1{ 2\”data\”: [{ 3\”type\”: \”articles\”, 4\”id\”: \”1\”, 5\”attributes\”: { 6\”title\”: \”JSON API paints my bikeshed!\” 7}, 8\”links\”: { 9\”self\”: \”http://example.com/articles/1\”10},11\”relationships\”: {12\”author\”: {13\”links\”: {14\”self\”: \”http://example.com/articles/1/relationships/author\”,15\”related\”: \”http://example.com/articles/1/author\”16},17\”data\”: {18\”type\”: \”people\”,19\”id\”: \”9\”20}21},22\”comments\”: {23\”links\”: {24\”self\”: \”http://example.com/articles/1/relationships/comments\”,25\”related\”: \”http://example.com/articles/1/comments\”26},27\”data\”: [{28\”type\”: \”comments\”,29\”id\”: \”5\”30}, {31\”type\”: \”comments\”,32\”id\”: \”12\”33}]34}35}36}],37\”included\”: [{38\”type\”: \”people\”,39\”id\”: \”9\”,40\”attributes\”: {41\”first-name\”: \”Dan\”,42\”last-name\”: \”Gebhardt\”,43\”twitter\”: \”dgeb\”44},45\”links\”: {46\”self\”: \”http://example.com/people/9\”47}48}, {49\”type\”: \”comments\”,50\”id\”: \”5\”,51\”attributes\”: {52\”body\”: \”First!\”53},54\”relationships\”: {55\”author\”: {56\”data\”: {57\”type\”: \”people\”,58\”id\”: \”2\”59}60}61},62\”links\”: {63\”self\”: \”http://example.com/comments/5\”64}65}, {66\”type\”: \”comments\”,67\”id\”: \”12\”,68\”attributes\”: {69\”body\”: \”I like XML better\”70},71\”relationships\”: {72\”author\”: {73\”data\”: {74\”type\”: \”people\”,75\”id\”: \”9\”76}77}78},79\”links\”: {80\”self\”: \”http://example.com/comments/12\”81}82}]83}
如果您查看included属性,您就会看到本文的所有相关资源。每个包含的文档都有一个type属性,该属性定义了返回的资源类型和指向文档终结点的链接。
如果仅通过id和type引用article中的author关系,并从included标记加载相关的people资源,可能会感到奇怪。但想象一下,当有多篇文章引用同一个author时,该文档在included数据中只包含一次引用的people。效率很高!包含相关资源
在上面的示例中,服务器包含响应中的所有关系,但您可能不希望默认情况下这样做,因为这会使响应有点膨胀。因此,规范提供了一种方法来指定响应中应包含哪些关系。
例如,如果您只需要包含author关系,则可以使用include请求参数调用端点。这将告诉服务器只发送带有响应的指定关系。
1GET>2Accept: application/vnd.api+json
如果需要多个关系,请用逗号(,)分隔这些关系。
在定义包含时,可以更进一步地包含嵌套关系。例如,您想要comments,在comments的authors中,您可以只包含comments.author:
1GET>2Accept: application/vnd.api+json
这种灵活性使得获取正确的资源变得轻而易举,允许您根据需要调整结果。稀疏字段集
当您使用复合文档时,您的请求可能会变得很大、很快。尤其是当包含的关系包含大量数据时。大多数情况下,您不需要在资源中定义每一个属性,而只需要诸如作者姓名之类的内容。JSON API为此用例提供稀疏字段集。
您可以通过设置fields请求参数来指定获取的字段。格式为fields[TYPE],因此,您可以按资源类型指定所需的字段。
1GET /articles?include=author&fields[articles]=>2Accept: application/vnd.api+json
此调用可以包括articles资源中的title和body字段以及people资源中的name字段。其他功能
服务器可以实现规范定义的其他一些功能。这些功能包括:包含、排序、分页和筛选。排序
如果服务器支持,您可以使用sort请求参数对记录进行排序。排序默认为升序,要降序排序,可以在字段前面加上-。
1GET>2Accept: application/vnd.api+json分页
如果服务器支持分页,它将提供一些额外的元属性和分页信息。服务器可以决定如何分页,可以是通过偏移量,也可以是直接页码。一个实现示例使用指向其他页面的所需链接,并在meta标记中包含一些元数据。
1{ 2links: { 3first:> 4last:> 5prev:> 6next: null 7}, 8meta: { 9current_page: 262,10from: 3916,11last_page: 262,12per_page: 15,13to: 3924,14total: 392415}16}筛选
规范说明很少

LaravelJSON API简介 为WP2原创文章,链接:https://www.wp2.cn/laravel/laraveljson-api%e7%ae%80%e4%bb%8b/