line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
# ABSTRACT: Data Abstraction Object class |
2
|
|
|
|
|
|
|
package PONAPI::DAO; |
3
|
|
|
|
|
|
|
|
4
|
8
|
|
|
8
|
|
124506
|
use Moose; |
|
8
|
|
|
|
|
1944599
|
|
|
8
|
|
|
|
|
61
|
|
5
|
|
|
|
|
|
|
|
6
|
8
|
|
|
8
|
|
60193
|
use PONAPI::DAO::Request::Retrieve; |
|
8
|
|
|
|
|
26
|
|
|
8
|
|
|
|
|
342
|
|
7
|
8
|
|
|
8
|
|
6067
|
use PONAPI::DAO::Request::RetrieveAll; |
|
8
|
|
|
|
|
29
|
|
|
8
|
|
|
|
|
334
|
|
8
|
8
|
|
|
8
|
|
6095
|
use PONAPI::DAO::Request::RetrieveRelationships; |
|
8
|
|
|
|
|
28
|
|
|
8
|
|
|
|
|
341
|
|
9
|
8
|
|
|
8
|
|
6155
|
use PONAPI::DAO::Request::RetrieveByRelationship; |
|
8
|
|
|
|
|
33
|
|
|
8
|
|
|
|
|
348
|
|
10
|
8
|
|
|
8
|
|
6135
|
use PONAPI::DAO::Request::Create; |
|
8
|
|
|
|
|
29
|
|
|
8
|
|
|
|
|
341
|
|
11
|
8
|
|
|
8
|
|
6063
|
use PONAPI::DAO::Request::CreateRelationships; |
|
8
|
|
|
|
|
36
|
|
|
8
|
|
|
|
|
339
|
|
12
|
8
|
|
|
8
|
|
5890
|
use PONAPI::DAO::Request::Update; |
|
8
|
|
|
|
|
34
|
|
|
8
|
|
|
|
|
386
|
|
13
|
8
|
|
|
8
|
|
5901
|
use PONAPI::DAO::Request::UpdateRelationships; |
|
8
|
|
|
|
|
31
|
|
|
8
|
|
|
|
|
338
|
|
14
|
8
|
|
|
8
|
|
6008
|
use PONAPI::DAO::Request::Delete; |
|
8
|
|
|
|
|
31
|
|
|
8
|
|
|
|
|
410
|
|
15
|
8
|
|
|
8
|
|
6015
|
use PONAPI::DAO::Request::DeleteRelationships; |
|
8
|
|
|
|
|
58
|
|
|
8
|
|
|
|
|
3965
|
|
16
|
|
|
|
|
|
|
|
17
|
|
|
|
|
|
|
has repository => ( |
18
|
|
|
|
|
|
|
is => 'ro', |
19
|
|
|
|
|
|
|
does => 'PONAPI::Repository', |
20
|
|
|
|
|
|
|
required => 1, |
21
|
|
|
|
|
|
|
); |
22
|
|
|
|
|
|
|
|
23
|
|
|
|
|
|
|
has version => ( |
24
|
|
|
|
|
|
|
is => 'ro', |
25
|
|
|
|
|
|
|
isa => 'Str', |
26
|
|
|
|
|
|
|
required => 1, |
27
|
|
|
|
|
|
|
); |
28
|
|
|
|
|
|
|
|
29
|
|
|
|
|
|
|
has json => ( |
30
|
|
|
|
|
|
|
is => 'ro', |
31
|
|
|
|
|
|
|
isa => 'JSON::XS', |
32
|
|
|
|
|
|
|
default => sub { JSON::XS->new->allow_nonref->utf8->canonical }, |
33
|
|
|
|
|
|
|
); |
34
|
|
|
|
|
|
|
|
35
|
32
|
|
|
32
|
1
|
92263
|
sub retrieve_all { shift->_action( 'PONAPI::DAO::Request::RetrieveAll' , @_ ) } |
36
|
55
|
|
|
55
|
1
|
87838
|
sub retrieve { shift->_action( 'PONAPI::DAO::Request::Retrieve' , @_ ) } |
37
|
16
|
|
|
16
|
1
|
31154
|
sub retrieve_relationships { shift->_action( 'PONAPI::DAO::Request::RetrieveRelationships' , @_ ) } |
38
|
15
|
|
|
15
|
0
|
30672
|
sub retrieve_by_relationship { shift->_action( 'PONAPI::DAO::Request::RetrieveByRelationship' , @_ ) } |
39
|
27
|
|
|
27
|
1
|
60576
|
sub create { shift->_action( 'PONAPI::DAO::Request::Create' , @_ ) } |
40
|
21
|
|
|
21
|
1
|
38208
|
sub create_relationships { shift->_action( 'PONAPI::DAO::Request::CreateRelationships' , @_ ) } |
41
|
26
|
|
|
26
|
1
|
56663
|
sub update { shift->_action( 'PONAPI::DAO::Request::Update' , @_ ) } |
42
|
15
|
|
|
15
|
1
|
28675
|
sub update_relationships { shift->_action( 'PONAPI::DAO::Request::UpdateRelationships' , @_ ) } |
43
|
20
|
|
|
20
|
1
|
40280
|
sub delete : method { shift->_action( 'PONAPI::DAO::Request::Delete' , @_ ) } |
44
|
16
|
|
|
16
|
1
|
37403
|
sub delete_relationships { shift->_action( 'PONAPI::DAO::Request::DeleteRelationships' , @_ ) } |
45
|
|
|
|
|
|
|
|
46
|
|
|
|
|
|
|
sub _action { |
47
|
243
|
|
|
243
|
|
484
|
my $self = shift; |
48
|
243
|
|
|
|
|
497
|
my $action_class = shift; |
49
|
|
|
|
|
|
|
|
50
|
243
|
100
|
|
|
|
1339
|
my $ponapi_parameters = @_ == 1 ? $_[0] : +{ @_ }; |
51
|
243
|
|
|
|
|
10387
|
$ponapi_parameters->{repository} = $self->repository; |
52
|
243
|
|
|
|
|
8526
|
$ponapi_parameters->{version} = $self->version; |
53
|
243
|
|
|
|
|
8277
|
$ponapi_parameters->{json} = $self->json; |
54
|
|
|
|
|
|
|
|
55
|
243
|
|
|
|
|
497
|
local $@; |
56
|
243
|
|
|
|
|
400
|
my @ret; |
57
|
|
|
|
|
|
|
eval { |
58
|
243
|
|
|
|
|
11450
|
@ret = $action_class->new($ponapi_parameters)->execute(); |
59
|
196
|
|
|
|
|
9093
|
1; |
60
|
243
|
100
|
|
|
|
481
|
} or do { |
61
|
47
|
|
100
|
|
|
1432
|
my $e = $@ || 'Unknown error'; |
62
|
47
|
|
|
|
|
8097
|
@ret = PONAPI::Exception |
63
|
|
|
|
|
|
|
->new_from_exception($e) |
64
|
|
|
|
|
|
|
->as_response; |
65
|
|
|
|
|
|
|
}; |
66
|
|
|
|
|
|
|
|
67
|
243
|
|
|
|
|
3743
|
return @ret; |
68
|
|
|
|
|
|
|
} |
69
|
|
|
|
|
|
|
|
70
|
|
|
|
|
|
|
__PACKAGE__->meta->make_immutable; |
71
|
8
|
|
|
8
|
|
76
|
no Moose; 1; |
|
8
|
|
|
|
|
19
|
|
|
8
|
|
|
|
|
58
|
|
72
|
|
|
|
|
|
|
|
73
|
|
|
|
|
|
|
__END__ |
74
|
|
|
|
|
|
|
|
75
|
|
|
|
|
|
|
=pod |
76
|
|
|
|
|
|
|
|
77
|
|
|
|
|
|
|
=encoding UTF-8 |
78
|
|
|
|
|
|
|
|
79
|
|
|
|
|
|
|
=head1 NAME |
80
|
|
|
|
|
|
|
|
81
|
|
|
|
|
|
|
PONAPI::DAO - Data Abstraction Object class |
82
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
=head1 VERSION |
84
|
|
|
|
|
|
|
|
85
|
|
|
|
|
|
|
version 0.002006 |
86
|
|
|
|
|
|
|
|
87
|
|
|
|
|
|
|
=head1 SYNOPSIS |
88
|
|
|
|
|
|
|
|
89
|
|
|
|
|
|
|
use PONAPI::DAO; |
90
|
|
|
|
|
|
|
my $dao = PONAPI::DAO->new( repository => $repository ); |
91
|
|
|
|
|
|
|
|
92
|
|
|
|
|
|
|
my ($status, $doc) = $dao->retrieve( type => $type, id => $id ); |
93
|
|
|
|
|
|
|
die "retrieve failed; status $status, $doc->{errors}[0]{detail}" |
94
|
|
|
|
|
|
|
if $doc->{errors}; |
95
|
|
|
|
|
|
|
|
96
|
|
|
|
|
|
|
use Data::Dumper; |
97
|
|
|
|
|
|
|
say Dumper($doc->{data}); |
98
|
|
|
|
|
|
|
|
99
|
|
|
|
|
|
|
# Fetch all resources of this type |
100
|
|
|
|
|
|
|
$dao->retrieve_all( type => $type ); |
101
|
|
|
|
|
|
|
|
102
|
|
|
|
|
|
|
# Fetch all the relationships of $rel_type for the requested resource |
103
|
|
|
|
|
|
|
$dao->retrieve_relationships( |
104
|
|
|
|
|
|
|
type => $type, |
105
|
|
|
|
|
|
|
id => $id, |
106
|
|
|
|
|
|
|
rel_type => $rel_type, |
107
|
|
|
|
|
|
|
); |
108
|
|
|
|
|
|
|
|
109
|
|
|
|
|
|
|
# Like the above, but fetches full resources instead of just relationships |
110
|
|
|
|
|
|
|
$dao->retrieve_by_relationship( |
111
|
|
|
|
|
|
|
type => $type, |
112
|
|
|
|
|
|
|
id => $id, |
113
|
|
|
|
|
|
|
rel_type => $rel_type, |
114
|
|
|
|
|
|
|
); |
115
|
|
|
|
|
|
|
|
116
|
|
|
|
|
|
|
# Create a new resource |
117
|
|
|
|
|
|
|
$dao->create( |
118
|
|
|
|
|
|
|
type => $type, |
119
|
|
|
|
|
|
|
data => { |
120
|
|
|
|
|
|
|
type => $type, |
121
|
|
|
|
|
|
|
attributes => { ... }, |
122
|
|
|
|
|
|
|
relationships => { ... }, |
123
|
|
|
|
|
|
|
} |
124
|
|
|
|
|
|
|
); |
125
|
|
|
|
|
|
|
|
126
|
|
|
|
|
|
|
# *Add* a new entry to the relationships between $type and $rel_type |
127
|
|
|
|
|
|
|
$dao->create_relationsips( |
128
|
|
|
|
|
|
|
type => $type, |
129
|
|
|
|
|
|
|
rel_type => $rel_type, |
130
|
|
|
|
|
|
|
data => [ |
131
|
|
|
|
|
|
|
{ ... }, |
132
|
|
|
|
|
|
|
] |
133
|
|
|
|
|
|
|
); |
134
|
|
|
|
|
|
|
|
135
|
|
|
|
|
|
|
# Update the attributes and/or relationships of a resource |
136
|
|
|
|
|
|
|
$dao->update( |
137
|
|
|
|
|
|
|
type => $type, |
138
|
|
|
|
|
|
|
id => $id, |
139
|
|
|
|
|
|
|
data => { |
140
|
|
|
|
|
|
|
type => $type, |
141
|
|
|
|
|
|
|
id => $id, |
142
|
|
|
|
|
|
|
attributes => { ... }, |
143
|
|
|
|
|
|
|
relationships => { ... }, |
144
|
|
|
|
|
|
|
}, |
145
|
|
|
|
|
|
|
); |
146
|
|
|
|
|
|
|
|
147
|
|
|
|
|
|
|
# Update the relationships of a given type for one resource |
148
|
|
|
|
|
|
|
$dao->update_relationships( |
149
|
|
|
|
|
|
|
type => $type, |
150
|
|
|
|
|
|
|
id => $id, |
151
|
|
|
|
|
|
|
rel_type => $rel_type, |
152
|
|
|
|
|
|
|
data => $update_data, |
153
|
|
|
|
|
|
|
); |
154
|
|
|
|
|
|
|
|
155
|
|
|
|
|
|
|
# Delete a resource |
156
|
|
|
|
|
|
|
$dao->delete( |
157
|
|
|
|
|
|
|
type => $type, |
158
|
|
|
|
|
|
|
id => $id, |
159
|
|
|
|
|
|
|
); |
160
|
|
|
|
|
|
|
|
161
|
|
|
|
|
|
|
# Delete the members from the relationship |
162
|
|
|
|
|
|
|
$dao->delete_relationships( |
163
|
|
|
|
|
|
|
type => $type, |
164
|
|
|
|
|
|
|
id => $id, |
165
|
|
|
|
|
|
|
rel_type => $rel_type, |
166
|
|
|
|
|
|
|
data => [ |
167
|
|
|
|
|
|
|
{ ... }, ... |
168
|
|
|
|
|
|
|
], |
169
|
|
|
|
|
|
|
); |
170
|
|
|
|
|
|
|
|
171
|
|
|
|
|
|
|
=head1 DESCRIPTION |
172
|
|
|
|
|
|
|
|
173
|
|
|
|
|
|
|
Data Access Object for the JSON API. This sits in between a server |
174
|
|
|
|
|
|
|
and a L<repository|"PONAPI::Repository">. |
175
|
|
|
|
|
|
|
|
176
|
|
|
|
|
|
|
All public DAO methods will return a 3-item list of a status, headers, |
177
|
|
|
|
|
|
|
and the response body; this can then be fed directly to a PSGI application: |
178
|
|
|
|
|
|
|
|
179
|
|
|
|
|
|
|
If present, the C<data> key of the response will contain either a |
180
|
|
|
|
|
|
|
resource, or an arrayref of resources. Resources are represented as |
181
|
|
|
|
|
|
|
plain hashrefs, and they B<must> include both a C<type> and C<id>; they |
182
|
|
|
|
|
|
|
may also contain additional keys. See L<http://jsonapi.org/format/#document-resource-objects> |
183
|
|
|
|
|
|
|
for a more in-depth description. |
184
|
|
|
|
|
|
|
|
185
|
|
|
|
|
|
|
=head1 METHODS |
186
|
|
|
|
|
|
|
|
187
|
|
|
|
|
|
|
=head2 new |
188
|
|
|
|
|
|
|
|
189
|
|
|
|
|
|
|
Create a new instance of PONAPI::DAO. |
190
|
|
|
|
|
|
|
|
191
|
|
|
|
|
|
|
my $DAO = PONAPI::DAO->new( |
192
|
|
|
|
|
|
|
repository => $repository, |
193
|
|
|
|
|
|
|
); |
194
|
|
|
|
|
|
|
|
195
|
|
|
|
|
|
|
Where C<$repository> implements the L<PONAPI::Repository> role. |
196
|
|
|
|
|
|
|
|
197
|
|
|
|
|
|
|
As expanded below in L</"Return value of update operations">, the JSON API specification requires some |
198
|
|
|
|
|
|
|
update operations returning C<200 OK> to also do a C<retrieve> and include |
199
|
|
|
|
|
|
|
it in the response. |
200
|
|
|
|
|
|
|
By default, C<PONAPI::DAO> will simply turn those C<200 OK> into |
201
|
|
|
|
|
|
|
C<202 Accepted>, avoiding the need to do the extra fetch. If needed, the |
202
|
|
|
|
|
|
|
full 200 responses can be re-enabled by passing |
203
|
|
|
|
|
|
|
C<respond_to_updates_with_200 =E<gt> 1,> to C<new>. |
204
|
|
|
|
|
|
|
|
205
|
|
|
|
|
|
|
=head1 API METHODS |
206
|
|
|
|
|
|
|
|
207
|
|
|
|
|
|
|
With the exception of C<create> and C<retrieve_all>, the type and id arguments are mandatory |
208
|
|
|
|
|
|
|
for all operations. |
209
|
|
|
|
|
|
|
|
210
|
|
|
|
|
|
|
=head2 retrieve |
211
|
|
|
|
|
|
|
|
212
|
|
|
|
|
|
|
Retrieve a resource. Returns both the status of the request and |
213
|
|
|
|
|
|
|
the document to be encoded. |
214
|
|
|
|
|
|
|
|
215
|
|
|
|
|
|
|
my ( $status, $doc ) = $dao->retrieve( type => "articles", id => 1 ); |
216
|
|
|
|
|
|
|
|
217
|
|
|
|
|
|
|
if ( $doc->{errors} ) { |
218
|
|
|
|
|
|
|
die "Welp! Got some errors: ", join "\n", |
219
|
|
|
|
|
|
|
map $_->{detail}, @{ $doc->{errors} }; |
220
|
|
|
|
|
|
|
} |
221
|
|
|
|
|
|
|
|
222
|
|
|
|
|
|
|
say $doc->{data}{attributes}{title}; |
223
|
|
|
|
|
|
|
|
224
|
|
|
|
|
|
|
This accepts several optional values: |
225
|
|
|
|
|
|
|
|
226
|
|
|
|
|
|
|
=over 4 |
227
|
|
|
|
|
|
|
|
228
|
|
|
|
|
|
|
=item fields |
229
|
|
|
|
|
|
|
|
230
|
|
|
|
|
|
|
Allows fetching only specific fields of the resource: |
231
|
|
|
|
|
|
|
|
232
|
|
|
|
|
|
|
# This will fetch the entire resource |
233
|
|
|
|
|
|
|
$dao->retrieve(type => "articles", id => 1); |
234
|
|
|
|
|
|
|
|
235
|
|
|
|
|
|
|
# This will only fetch the title attribute |
236
|
|
|
|
|
|
|
$dao->retrieve( |
237
|
|
|
|
|
|
|
type => "articles", |
238
|
|
|
|
|
|
|
id => 1, |
239
|
|
|
|
|
|
|
fields => { articles => [qw/ title /] }, |
240
|
|
|
|
|
|
|
); |
241
|
|
|
|
|
|
|
|
242
|
|
|
|
|
|
|
Note how the fields fetched are requested per attribute type. This allows you to |
243
|
|
|
|
|
|
|
request specific fields in resources fetched through C<include>. |
244
|
|
|
|
|
|
|
|
245
|
|
|
|
|
|
|
=item include |
246
|
|
|
|
|
|
|
|
247
|
|
|
|
|
|
|
Allows including related resources. |
248
|
|
|
|
|
|
|
|
249
|
|
|
|
|
|
|
# The response will contain a top-level 'include' key with the |
250
|
|
|
|
|
|
|
# article's author |
251
|
|
|
|
|
|
|
$dao->retrieve(type => "articles", id => 1, include => [qw/ author /]); |
252
|
|
|
|
|
|
|
|
253
|
|
|
|
|
|
|
# We can combine include with C<fields> to fetch just the author's name: |
254
|
|
|
|
|
|
|
my $response = $dao->retrieve( |
255
|
|
|
|
|
|
|
id => 1, |
256
|
|
|
|
|
|
|
type => "articles", |
257
|
|
|
|
|
|
|
include => [qw/ author /], |
258
|
|
|
|
|
|
|
fields => { author => [qw/ name /] } |
259
|
|
|
|
|
|
|
); |
260
|
|
|
|
|
|
|
|
261
|
|
|
|
|
|
|
These will show up in the document in the top-level "included" key. |
262
|
|
|
|
|
|
|
|
263
|
|
|
|
|
|
|
=item page |
264
|
|
|
|
|
|
|
|
265
|
|
|
|
|
|
|
Used to provide pagination information to the underlaying repository. |
266
|
|
|
|
|
|
|
Each implementation may provide a different pagination strategy. |
267
|
|
|
|
|
|
|
|
268
|
|
|
|
|
|
|
=item filter |
269
|
|
|
|
|
|
|
|
270
|
|
|
|
|
|
|
Entirely implementation-specific. |
271
|
|
|
|
|
|
|
|
272
|
|
|
|
|
|
|
=back |
273
|
|
|
|
|
|
|
|
274
|
|
|
|
|
|
|
=head2 retrieve_all |
275
|
|
|
|
|
|
|
|
276
|
|
|
|
|
|
|
As you might expect, this is similar to C<retrieve>. The returned document |
277
|
|
|
|
|
|
|
will contain an arrayref of resource, rather than a single resource. |
278
|
|
|
|
|
|
|
|
279
|
|
|
|
|
|
|
Depending on the implementation, you may be able to combine this with |
280
|
|
|
|
|
|
|
C<filter> to retrieve multiple specific resources in a single request. |
281
|
|
|
|
|
|
|
|
282
|
|
|
|
|
|
|
C<retrieve_all> takes all the same optional arguments as C<retrieve>, |
283
|
|
|
|
|
|
|
plus one of its own: |
284
|
|
|
|
|
|
|
|
285
|
|
|
|
|
|
|
=over 1 |
286
|
|
|
|
|
|
|
|
287
|
|
|
|
|
|
|
=item sort |
288
|
|
|
|
|
|
|
|
289
|
|
|
|
|
|
|
Sorting strategy for the request. Implementation-specific. |
290
|
|
|
|
|
|
|
|
291
|
|
|
|
|
|
|
=back |
292
|
|
|
|
|
|
|
|
293
|
|
|
|
|
|
|
=head2 retrieve_relationships |
294
|
|
|
|
|
|
|
|
295
|
|
|
|
|
|
|
This retrieves all relationships of C<$type>. Will return either an |
296
|
|
|
|
|
|
|
arrayref or a hashref, depending on whether the requested relationship is |
297
|
|
|
|
|
|
|
one-to-one or one-to-many: |
298
|
|
|
|
|
|
|
|
299
|
|
|
|
|
|
|
# Retrieves all comments made for an article |
300
|
|
|
|
|
|
|
$doc = $dao->retrieve_relationships( |
301
|
|
|
|
|
|
|
type => "articles", |
302
|
|
|
|
|
|
|
id => 1, |
303
|
|
|
|
|
|
|
rel_type => "comments", |
304
|
|
|
|
|
|
|
); |
305
|
|
|
|
|
|
|
# articles-to-comments is one-to-many, so it returns an arrayref |
306
|
|
|
|
|
|
|
say scalar @{ $doc->{data} }; |
307
|
|
|
|
|
|
|
|
308
|
|
|
|
|
|
|
$doc = $dao->retrieve_relationships( |
309
|
|
|
|
|
|
|
type => "articles", |
310
|
|
|
|
|
|
|
id => 1, |
311
|
|
|
|
|
|
|
rel_type => "author", |
312
|
|
|
|
|
|
|
); |
313
|
|
|
|
|
|
|
# articles-to-author is one-to-one, so it returns a hashref |
314
|
|
|
|
|
|
|
say $doc->{data}{id}; |
315
|
|
|
|
|
|
|
|
316
|
|
|
|
|
|
|
Takes two optional arguments, C<filter> and C<page>; both are entirely |
317
|
|
|
|
|
|
|
implementation specific. |
318
|
|
|
|
|
|
|
|
319
|
|
|
|
|
|
|
=head2 retrieve_by_relationships |
320
|
|
|
|
|
|
|
|
321
|
|
|
|
|
|
|
Like C<retrieve_relationships>, but fetches full resources, rather than |
322
|
|
|
|
|
|
|
identifier objects. |
323
|
|
|
|
|
|
|
|
324
|
|
|
|
|
|
|
# One-to-many relationship, this returns an arrayref of resource hashrefs. |
325
|
|
|
|
|
|
|
$dao->retrieve_by_relationships( |
326
|
|
|
|
|
|
|
type => "articles", |
327
|
|
|
|
|
|
|
id => 1, |
328
|
|
|
|
|
|
|
rel_type => "comments", |
329
|
|
|
|
|
|
|
); |
330
|
|
|
|
|
|
|
# Same as: |
331
|
|
|
|
|
|
|
$doc = $dao->retrieve_relationships( |
332
|
|
|
|
|
|
|
type => "articles", |
333
|
|
|
|
|
|
|
id => 1, |
334
|
|
|
|
|
|
|
rel_type => "comments", |
335
|
|
|
|
|
|
|
); |
336
|
|
|
|
|
|
|
$comments = $dao->retrieve_all( |
337
|
|
|
|
|
|
|
type => $doc->{data}{type}, |
338
|
|
|
|
|
|
|
filter => { id => [ map $_->{id}, @{ $doc->{data} } ] }, |
339
|
|
|
|
|
|
|
); |
340
|
|
|
|
|
|
|
|
341
|
|
|
|
|
|
|
# One-to-one relationship |
342
|
|
|
|
|
|
|
$doc = $dao->retrieve_relationships( |
343
|
|
|
|
|
|
|
type => "articles", |
344
|
|
|
|
|
|
|
id => 1, |
345
|
|
|
|
|
|
|
rel_type => "author", |
346
|
|
|
|
|
|
|
); |
347
|
|
|
|
|
|
|
# Same as: |
348
|
|
|
|
|
|
|
$doc = $dao->retrieve_relationships( |
349
|
|
|
|
|
|
|
type => "articles", |
350
|
|
|
|
|
|
|
id => 1, |
351
|
|
|
|
|
|
|
rel_type => "author", |
352
|
|
|
|
|
|
|
); |
353
|
|
|
|
|
|
|
$author = $dao->retrieve( |
354
|
|
|
|
|
|
|
type => $doc->{data}{type}, |
355
|
|
|
|
|
|
|
id => $doc->{data}{id}, |
356
|
|
|
|
|
|
|
); |
357
|
|
|
|
|
|
|
|
358
|
|
|
|
|
|
|
Takes the same optional arguments as C<retrieve> and C<retrieve_all>, whichever is applicable. |
359
|
|
|
|
|
|
|
|
360
|
|
|
|
|
|
|
=head2 delete |
361
|
|
|
|
|
|
|
|
362
|
|
|
|
|
|
|
Deletes a resource. |
363
|
|
|
|
|
|
|
|
364
|
|
|
|
|
|
|
$dao->delete( type => "articles", id => 1 ); |
365
|
|
|
|
|
|
|
|
366
|
|
|
|
|
|
|
May or may not return a document with a top-level meta key. |
367
|
|
|
|
|
|
|
|
368
|
|
|
|
|
|
|
=head2 create |
369
|
|
|
|
|
|
|
|
370
|
|
|
|
|
|
|
Creates a resource. |
371
|
|
|
|
|
|
|
|
372
|
|
|
|
|
|
|
$dao->create( |
373
|
|
|
|
|
|
|
type => "articles", |
374
|
|
|
|
|
|
|
data => { |
375
|
|
|
|
|
|
|
type => "articles", |
376
|
|
|
|
|
|
|
attributes => { ... }, |
377
|
|
|
|
|
|
|
relationships => { ... }, |
378
|
|
|
|
|
|
|
}, |
379
|
|
|
|
|
|
|
); |
380
|
|
|
|
|
|
|
|
381
|
|
|
|
|
|
|
This is one of the few methods where the C<id> is optional. If provided, the underlaying |
382
|
|
|
|
|
|
|
implementation may choose to use it, instead of generating a new idea for the created resource. |
383
|
|
|
|
|
|
|
|
384
|
|
|
|
|
|
|
If successful, the response will include both a C<Location> header specifying |
385
|
|
|
|
|
|
|
where the new resource resides, and a document that includes the newly |
386
|
|
|
|
|
|
|
created resource. |
387
|
|
|
|
|
|
|
|
388
|
|
|
|
|
|
|
=head2 update |
389
|
|
|
|
|
|
|
|
390
|
|
|
|
|
|
|
Updates a resource. This can be used to either update the resource attributes, |
391
|
|
|
|
|
|
|
or its relationships; for the latter, you may want to consider using C<update_relationships>, |
392
|
|
|
|
|
|
|
C<create_relationships>, or C<delete_relationships> instead. |
393
|
|
|
|
|
|
|
|
394
|
|
|
|
|
|
|
# Change article's title |
395
|
|
|
|
|
|
|
$dao->update( |
396
|
|
|
|
|
|
|
type => "articles", |
397
|
|
|
|
|
|
|
id => 1, |
398
|
|
|
|
|
|
|
data => { |
399
|
|
|
|
|
|
|
type => "articles", |
400
|
|
|
|
|
|
|
id => 1, |
401
|
|
|
|
|
|
|
attributes => { title => "Updated title!" }, |
402
|
|
|
|
|
|
|
} |
403
|
|
|
|
|
|
|
); |
404
|
|
|
|
|
|
|
|
405
|
|
|
|
|
|
|
# Change the article's author |
406
|
|
|
|
|
|
|
$dao->update( |
407
|
|
|
|
|
|
|
type => "articles", |
408
|
|
|
|
|
|
|
id => 1, |
409
|
|
|
|
|
|
|
data => { |
410
|
|
|
|
|
|
|
type => "articles", |
411
|
|
|
|
|
|
|
id => 1, |
412
|
|
|
|
|
|
|
relationships => { |
413
|
|
|
|
|
|
|
author => { type => "people", id => 99 }, |
414
|
|
|
|
|
|
|
}, |
415
|
|
|
|
|
|
|
}, |
416
|
|
|
|
|
|
|
); |
417
|
|
|
|
|
|
|
|
418
|
|
|
|
|
|
|
# Switch the tags of the article to a new set of tags |
419
|
|
|
|
|
|
|
$dao->update( |
420
|
|
|
|
|
|
|
type => "articles", |
421
|
|
|
|
|
|
|
id => 1, |
422
|
|
|
|
|
|
|
data => { |
423
|
|
|
|
|
|
|
type => "articles", |
424
|
|
|
|
|
|
|
id => 1, |
425
|
|
|
|
|
|
|
relationships => { |
426
|
|
|
|
|
|
|
tags => [ |
427
|
|
|
|
|
|
|
{ type => "tag", id => 4 }, |
428
|
|
|
|
|
|
|
{ type => "tag", id => 5 }, |
429
|
|
|
|
|
|
|
], |
430
|
|
|
|
|
|
|
}, |
431
|
|
|
|
|
|
|
}, |
432
|
|
|
|
|
|
|
); |
433
|
|
|
|
|
|
|
|
434
|
|
|
|
|
|
|
Missing attributes or relationships will B<not> be modified. |
435
|
|
|
|
|
|
|
|
436
|
|
|
|
|
|
|
=head3 Return value of update operations |
437
|
|
|
|
|
|
|
|
438
|
|
|
|
|
|
|
C<update>, C<delete_relationships>, C<create_relationships>, and |
439
|
|
|
|
|
|
|
C<update_relationships> all follow the same rules for their responses. |
440
|
|
|
|
|
|
|
|
441
|
|
|
|
|
|
|
If successful, they will return with either: |
442
|
|
|
|
|
|
|
|
443
|
|
|
|
|
|
|
=over 3 |
444
|
|
|
|
|
|
|
|
445
|
|
|
|
|
|
|
=item 200 OK |
446
|
|
|
|
|
|
|
|
447
|
|
|
|
|
|
|
If the update was successful and no extra data was updated, the response |
448
|
|
|
|
|
|
|
will include a top-level C<meta> key, with a description of what was |
449
|
|
|
|
|
|
|
updated. |
450
|
|
|
|
|
|
|
|
451
|
|
|
|
|
|
|
Meanwhile, if the update was successful but more data than requested was |
452
|
|
|
|
|
|
|
updated -- Consider C<updated-at> columns in a table -- then the request |
453
|
|
|
|
|
|
|
will return both a top-level C<meta> key, and a top-level C<data> key, |
454
|
|
|
|
|
|
|
containing the results of a C<retrieve> operation on the primary updated |
455
|
|
|
|
|
|
|
resource. Since this behavior can be undesirable, unless C<PONAPI::DAO-E<gt>new> |
456
|
|
|
|
|
|
|
was passed C<respond_to_updates_with_200 =E<gt> 1>, this sort of response is |
457
|
|
|
|
|
|
|
disabled, and the server will instead respond with a L</"202 Accepted">, |
458
|
|
|
|
|
|
|
described below. |
459
|
|
|
|
|
|
|
|
460
|
|
|
|
|
|
|
=item 202 Accepted |
461
|
|
|
|
|
|
|
|
462
|
|
|
|
|
|
|
The response will include a top-level C<meta> key, with a human-readable |
463
|
|
|
|
|
|
|
description of the success. |
464
|
|
|
|
|
|
|
|
465
|
|
|
|
|
|
|
This is used when the server accepted the operation, but hasn't yet |
466
|
|
|
|
|
|
|
completed it; "Completed" being purposely very ambiguous. In a SQL-based |
467
|
|
|
|
|
|
|
implementation, it might simply mean that the change hasn't fully replicated |
468
|
|
|
|
|
|
|
yet. |
469
|
|
|
|
|
|
|
|
470
|
|
|
|
|
|
|
=item 204 No Content |
471
|
|
|
|
|
|
|
|
472
|
|
|
|
|
|
|
If the operation was successful and nothing beyond the requested was modified, |
473
|
|
|
|
|
|
|
the server may choose to send a 204 with no body, instead of a 200. |
474
|
|
|
|
|
|
|
|
475
|
|
|
|
|
|
|
=back |
476
|
|
|
|
|
|
|
|
477
|
|
|
|
|
|
|
=head2 delete_relationships |
478
|
|
|
|
|
|
|
|
479
|
|
|
|
|
|
|
Remove members from a one-to-many relationship. |
480
|
|
|
|
|
|
|
|
481
|
|
|
|
|
|
|
# Remove two comments from the article |
482
|
|
|
|
|
|
|
$dao->delete( |
483
|
|
|
|
|
|
|
type => "articles", |
484
|
|
|
|
|
|
|
id => 1, |
485
|
|
|
|
|
|
|
rel_type => "comments', |
486
|
|
|
|
|
|
|
data => [ |
487
|
|
|
|
|
|
|
{ type => "comment", id => 44 }, |
488
|
|
|
|
|
|
|
{ type => "comment", id => 89 }, |
489
|
|
|
|
|
|
|
], |
490
|
|
|
|
|
|
|
); |
491
|
|
|
|
|
|
|
|
492
|
|
|
|
|
|
|
See also L</"Return value of update operations">. |
493
|
|
|
|
|
|
|
|
494
|
|
|
|
|
|
|
=head2 update_relationships |
495
|
|
|
|
|
|
|
|
496
|
|
|
|
|
|
|
Update the relationships of C<$rel_type>; this will replace all relationships |
497
|
|
|
|
|
|
|
of the requested type with the ones provided. Note that different semantics |
498
|
|
|
|
|
|
|
are used for one-to-one and one-to-many relationships: |
499
|
|
|
|
|
|
|
|
500
|
|
|
|
|
|
|
# Replace all comments |
501
|
|
|
|
|
|
|
$dao->update_relationships( |
502
|
|
|
|
|
|
|
type => "articles", |
503
|
|
|
|
|
|
|
id => 1, |
504
|
|
|
|
|
|
|
rel_type => "comments", |
505
|
|
|
|
|
|
|
# articles-to-comments is one-to-many, so it gets an arrayref |
506
|
|
|
|
|
|
|
data => [ { ... }, { ... } ], |
507
|
|
|
|
|
|
|
); |
508
|
|
|
|
|
|
|
|
509
|
|
|
|
|
|
|
# Change the author of the article |
510
|
|
|
|
|
|
|
$dao->update_relationships( |
511
|
|
|
|
|
|
|
type => "articles", |
512
|
|
|
|
|
|
|
id => 1, |
513
|
|
|
|
|
|
|
rel_type => "author", |
514
|
|
|
|
|
|
|
# articles-to-authors is one-to-one, so it gets a simple hashref |
515
|
|
|
|
|
|
|
data => { type => "people", id => 42 }, |
516
|
|
|
|
|
|
|
); |
517
|
|
|
|
|
|
|
|
518
|
|
|
|
|
|
|
# Clear the comments of an article |
519
|
|
|
|
|
|
|
$dao->update_relationships( |
520
|
|
|
|
|
|
|
type => "articles", |
521
|
|
|
|
|
|
|
id => 1, |
522
|
|
|
|
|
|
|
rel_type => "comments", |
523
|
|
|
|
|
|
|
# Empty array to clear out a one-to-many |
524
|
|
|
|
|
|
|
data => [], |
525
|
|
|
|
|
|
|
); |
526
|
|
|
|
|
|
|
|
527
|
|
|
|
|
|
|
# Clear the author of the relationship |
528
|
|
|
|
|
|
|
$dao->update_relationships( |
529
|
|
|
|
|
|
|
type => "articles", |
530
|
|
|
|
|
|
|
id => 1, |
531
|
|
|
|
|
|
|
rel_type => "author", |
532
|
|
|
|
|
|
|
# undef to clear out one-to-one |
533
|
|
|
|
|
|
|
data => undef, |
534
|
|
|
|
|
|
|
); |
535
|
|
|
|
|
|
|
|
536
|
|
|
|
|
|
|
See also L</"Return value of update operations">. |
537
|
|
|
|
|
|
|
|
538
|
|
|
|
|
|
|
=head2 create_relationships |
539
|
|
|
|
|
|
|
|
540
|
|
|
|
|
|
|
Adds a new member to the specified one-to-many relationship. |
541
|
|
|
|
|
|
|
|
542
|
|
|
|
|
|
|
# Add a new, existing comment to the article |
543
|
|
|
|
|
|
|
$dao->create_relationships( |
544
|
|
|
|
|
|
|
type => "articles", |
545
|
|
|
|
|
|
|
id => 1, |
546
|
|
|
|
|
|
|
rel_type => "comments", |
547
|
|
|
|
|
|
|
data => [ |
548
|
|
|
|
|
|
|
{ type => "comment", id => 55 }, |
549
|
|
|
|
|
|
|
], |
550
|
|
|
|
|
|
|
); |
551
|
|
|
|
|
|
|
|
552
|
|
|
|
|
|
|
See also L</"Return value of update operations">. |
553
|
|
|
|
|
|
|
|
554
|
|
|
|
|
|
|
=head1 AUTHORS |
555
|
|
|
|
|
|
|
|
556
|
|
|
|
|
|
|
=over 4 |
557
|
|
|
|
|
|
|
|
558
|
|
|
|
|
|
|
=item * |
559
|
|
|
|
|
|
|
|
560
|
|
|
|
|
|
|
Mickey Nasriachi <mickey@cpan.org> |
561
|
|
|
|
|
|
|
|
562
|
|
|
|
|
|
|
=item * |
563
|
|
|
|
|
|
|
|
564
|
|
|
|
|
|
|
Stevan Little <stevan@cpan.org> |
565
|
|
|
|
|
|
|
|
566
|
|
|
|
|
|
|
=item * |
567
|
|
|
|
|
|
|
|
568
|
|
|
|
|
|
|
Brian Fraser <hugmeir@cpan.org> |
569
|
|
|
|
|
|
|
|
570
|
|
|
|
|
|
|
=back |
571
|
|
|
|
|
|
|
|
572
|
|
|
|
|
|
|
=head1 COPYRIGHT AND LICENSE |
573
|
|
|
|
|
|
|
|
574
|
|
|
|
|
|
|
This software is copyright (c) 2016 by Mickey Nasriachi, Stevan Little, Brian Fraser. |
575
|
|
|
|
|
|
|
|
576
|
|
|
|
|
|
|
This is free software; you can redistribute it and/or modify it under |
577
|
|
|
|
|
|
|
the same terms as the Perl 5 programming language system itself. |
578
|
|
|
|
|
|
|
|
579
|
|
|
|
|
|
|
=cut |