File Coverage

blib/lib/Catmandu/Store/REST.pm
Criterion Covered Total %
statement 9 9 100.0
branch n/a
condition n/a
subroutine 3 3 100.0
pod n/a
total 12 12 100.0


line stmt bran cond sub pod time code
1             package Catmandu::Store::REST;
2              
3             our $VERSION = '0.01';
4              
5 1     1   865 use Catmandu::Sane;
  1         125950  
  1         7  
6              
7 1     1   225 use Moo;
  1         3  
  1         5  
8 1     1   706 use Catmandu::Store::REST::Bag;
  1         4  
  1         107  
9              
10             with 'Catmandu::Store';
11              
12             has base_url => (is => 'ro', required => 1);
13             has query_string => (is => 'ro', default => sub { return ''; });
14             # TODO: support basic authentication
15              
16             1;
17             __END__
18              
19             =encoding utf-8
20              
21             =head1 NAME
22              
23             Catmandu::Store::REST - Store/retrieve items from a JSON REST-API endpoint
24              
25             =head1 SYNOPSIS
26              
27             # From the command line
28             $ catmandu export REST --id 1234 --base_url https://www.example.org/api/v1/books --query_string /page/1 to YAML
29            
30             # From a Catmandu Fix
31             lookup_in_store(
32             book_id,
33             REST,
34             base_url: https://www.example.org/api/v1/books,
35             query_string: /page/1
36             )
37              
38             =head1 DESCRIPTION
39              
40             # From a Catmandu Fix
41             lookup_in_store(
42             book_id,
43             REST,
44             base_url: https://www.example.org/api/v1/books,
45             query_string: /page/1
46             )
47              
48             Uses a RESTful API as a L<Catmandu::Store|http://librecat.org/Catmandu/#stores>.
49              
50             The module allows you to use a RESTful API that uses JSON as data format and uses the URL format
51             C<[base_url]/[id][query_string]> as a I<Store> for I<Catmandu>.
52              
53             Retrieving (C<GET>), adding (C<POST>), updating (C<PUT>) and deleting (C<DELETE>) single items is
54             supported. Data must be provided as JSON by the API, and the API must accept JSON for C<PUT>/C<POST>
55             requests. The URL must be of the format C<[base_url]/[id][query_string]>, where the C<id>
56             is absent for C<POST> requests.
57              
58             =head1 PARAMETERS
59              
60             You must provide the C<base_url> parameter.
61              
62             =over
63              
64             =item C<base_url>
65              
66             base url of the API endpoint (the entire url before the ID) (e.g. I<https://www.example.org/api/v1/books>).
67              
68             =item C<query_string>
69              
70             an optional query string that comes behind the ID (e.g. I</page/1> where the complete URL is
71             I<https://www.example.org/api/v1/books/1/page/1>).
72              
73             =back
74              
75             =head1 AUTHOR
76              
77             Pieter De Praetere E<lt>pieter@packed.beE<gt>
78              
79             =head1 COPYRIGHT
80              
81             Copyright 2017- PACKED vzw
82              
83             =head1 LICENSE
84              
85             This library is free software; you can redistribute it and/or modify
86             it under the same terms as Perl itself.
87              
88             =head1 SEE ALSO
89              
90             =cut