8000 [Docs] Add docs for inclusion of related resources (#120) · Naxon/laravel-json-api@58ab6ec · GitHub
[go: up one dir, main page]
Skip to content

Commit 58ab6ec

Browse files
GIANTCRABlindyhopchris
GIANTCRAB
authored and
lindyhopchris
committed
[Docs] Add docs for inclusion of related resources (cloudcreativity#120)
Add a new chapter on inclusion of related resources.
1 parent 5aab3dd commit 58ab6ec

File tree

3 files changed

+163
-1
lines changed

3 files changed

+163
-1
lines changed

‎docs/custom/controllers.md

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,7 +141,6 @@ controller:
141141
2. `readRelationship()`
142142

143143
### Read Related Resource
144-
145144
If you link one resource to another through relationship, you'll need this to read the related resource.
146145

147146
```php

‎docs/features/inclusion.md

Lines changed: 162 additions & 0 deletions
Original file line numberDi 8000 ff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# Inclusion
2+
3+
## Introduction
4+
5+
This package supports the specification of [JSON API Inclusion of Related Resources](http://jsonapi.org/format/1.0/#fetching-includes). This allows you to load all the data of the specified resources that is bounded by relationship.
6+
7+
### Using Include Parameter
8+
9+
Per the specification, the client is able to request for the inclusion of related resources through the following HTTP request:
10+
11+
```http
12+
GET /api/posts?include=comments HTTP/2.0
13+
Accept: application/vnd.api+json
14+
```
15+
16+
However, by default, this package denies inclusion of related resources via parameter and would throw the follow error message.
17+
18+
```json
19+
{
20+
"errors": [
21+
{
22+
"title": "Include paths should contain only allowed ones.",
23+
"source": {
24+
"parameter": "include"
25+
}
26+
}
27+
]
28+
}
29+
30+
```
31+
32+
To allow certain resources to be included using request parameters, it must be manually enabled through the resource's `Validators.php` file.
33+
34+
```php
35+
namespace App\JsonApiV1\Posts;
36+
37+
class Validators extends AbstractValidatorProvider
38+
{
39+
protected $allowedIncludePaths = [
40+
'comments'
41+
];
42+
43+
/* Your code here ...*/
44+
}
45+
```
46+
47+
48+
### Auto Inclusion
49+
50+
It is possible to force the inclusion of certain related resources; displaying it even when the client did not specify the related resource in the include parameter. To enable the automatic inclusion of resources, edit the resource's `Schema.php` file.
51+
52+
```php
53+
namespace App\JsonApiV1\Posts;
54+
55+
class Schema extends EloquentSchema
56+
{
57+
58+
/* Your code here ...*/
59+
60+
public function getIncludePaths()
61+
{
62+
return [
63+
'comments'
64+
];
65+
}
66+
}
67+
```
68+
69+
And when the client sends the following request:
70+
71+
```http
72+
GET /api/posts HTTP/2.0
73+
Accept: application/vnd.api+json
74+
```
75+
76+
The response would look something like this:
77+
78+
```json
79+
{
80+
"data": [
81+
{
82+
"type": "posts",
83+
"id": "6118bf58-7374-4e9a-9843-d1b0e53ac0b9",
84+
"attributes": {
85+
"created-at": "2017-10-14T07:56:44+00:00",
86+
"updated-at": "2017-10-14T07:56:44+00:00",
87+
"title": "Bernadine McClure",
88+
"description": "Provident recusandae est rem consequatur. Et alias ut culpa architecto eligendi et temporibus. Aliquam ipsa vitae mollitia totam fuga."
89+
},
90+
"relationships": {
91+
"comments": {
92+
"data": [
93+
{
94+
"type": "comments",
95+
"id": "3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1"
96+
},
97+
{
98+
"type": "comments",
99+
"id": "bb3dd8a2-8678-480e-b477-87c8fddc5702"
100+
}
101+
],
102+
"meta": {
103+
"total": 2
104+
},
105+
"links": {
106+
"self": "http://localhost:8000/api/v1/posts/6118bf58-7374-4e9a-9843-d1b0e53ac0b9/relationships/comments",
107+
"related": "http://localhost:8000/api/v1/posts/6118bf58-7374-4e9a-9843-d1b0e53ac0b9/comments"
108+
}
109+
}
110+
},
111+
"links": {
112+
"self": "http://localhost:8000/api/v1/posts/6118bf58-7374-4e9a-9843-d1b0e53ac0b9"
113+
}
114+
}
115+
],
116+
"included": [
117+
{
118+
"type": "comments",
119+
"id": "3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1",
120+
"attributes": {
121+
"created-at": "2017-10-14T09:47:09+00:00",
122+
"updated-at": "2017-10-14T09:47:09+00:00",
123+
"description": "Excellent post!"
124+
},
125+
"relationships": {
126+
"post": {
127+
"data": {
128+
"type": "posts",
129+
"id": "6118bf58-7374-4e9a-9843-d1b0e53ac0b9"
130+
},
131+
"links": {
132+
"self": "http://localhost:8000/api/v1/comments/3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1/relationships/post",
133+
"related": "http://localhost:8000/api/v1/comments/3813a5ba-3d7b-432d-aa0d-eb0c3bd4e1a1/post"
134+
}
135+
}
136+
}
1 10AC5 37+
},
138+
{
139+
"type": "comments",
140+
"id": "bb3dd8a2-8678-480e-b477-87c8fddc5702",
141+
"attributes": {
142+
"created-at": "2017-10-14T07:57:52+00:00",
143+
"updated-at": "2017-10-14T07:57:52+00:00",
144+
"description": "I really like your post!"
145+
},
146+
"relationships": {
147+
"post": {
148+
"data": {
149+
"type": "posts",
150+
"id": "6118bf58-7374-4e9a-9843-d1b0e53ac0b9"
151+
},
152+
"links": {
153+
"self": "http://localhost:8000/api/v1/comments/bb3dd8a2-8678-480e-b477-87c8fddc5702/relationships/post",
154+
"related": "http://localhost:8000/api/v1/comments/bb3dd8a2-8678-480e-b477-87c8fddc5702/post"
155+
}
156+
}
157+
}
158+
}
159+
]
160+
}
161+
162+
```

‎mkdocs.yml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ pages:
1616
- Non-Eloquent:
1717
- Controllers: custom/controllers.md
1818
- Digging Deeper:
19+
- Inclusion: features/inclusion.md
1920
- Broadcasting: features/broadcasting.md
2021
- Helpers: features/helpers.md
2122
- HTTP Clients: features/http-clients.md

0 commit comments

Comments
 (0)
0