1NAME
2 McBain::WithPSGI - Load a McBain API as a RESTful PSGI web service
3
4SYNOPSIS
5 # write your API as you normally would, and create
6 # a simple psgi file:
7
8 #!/usr/bin/perl -w
9
10 use warnings;
11 use strict;
12 use MyAPI -withPSGI;
13
14 my $app = MyAPI->to_app;
15
16DESCRIPTION
17 "McBain::WithPSGI" turns your McBain API into a RESTful PSGI web service
18 based on Plack, thus making "McBain" a web application framework.
19
20 The created web service will be a JSON-in JSON-out service. Requests to
21 your application are expected to have a "Content-Type" of
22 "application/json; charset=UTF-8". The JSON body of a request will be
23 the payload. The results of the API will be formatted into JSON as well.
24
25 Note that if an API method does not return a hash-ref, this runner
26 module will automatically turn it into a hash-ref to ensure that
27 conversion into JSON will be possible. The created hash-ref will have
28 one key - holding the method's name, with whatever was returned from the
29 method as its value. For example, if method "GET:/divide" in topic
30 "/math" returns an integer (say 7), then the client will get the JSON "{
31 "GET:/math/divide": 7 }".
32
33 SUPPORTED HTTP METHODS
34 This runner support all methods natively supported by McBain. That is:
35 "GET", "PUT", "POST", "DELETE" and "OPTIONS". To add support for "HEAD"
36 requests, use Plack::Middleware::Head.
37
38 The "OPTIONS" method is special. It returns a list of all HTTP methods
39 allowed by a specific route (in the "Allow" header). The response body
40 will be the same hash-ref returned by "McBain" for "OPTIONS" requests,
41 JSON encoded.
42
43 CAVEATS AND CONSIDERATIONS
44 The HTTP protocol does not allow "GET" requests to have content, so your
45 "GET" routes will not be able to receive parameters from a request's
46 JSON body as all other methods do. If your "GET" routes *must* receive
47 parameters (for example, you might have a route that returns a list of
48 objects with support for pagination), "McBain::WithPSGI" supports
49 parameters from the query string. They will be validated like all
50 parameters, and they can be used in non-"GET" requests too. Note that
51 they take precedence over body parameters.
52
53 The downside to this is that the parameters cannot be complex
54 structures, though if the query string defines a certain key several
55 times, its generated value will be an array reference. For example,
56 let's look at the following route:
57
58 get '/params_from_query' => (
59 params => {
60 some_string => { required => 1 },
61 some_array => { array => 1, min_length => 2 }
62 },
63 cb => sub {
64 my ($api, $params) = @_;
65 return $params;
66 }
67 );
68
69 This route isn't particularly interesting, as it simply returns the
70 parameters it receives. It does, however, enforce the existence of the
71 "some_string" parameter, and expects "some_array" to be an array
72 reference of at least 2 items. A request to
73 "/params_from_query?some_string=this_is_my_string&some_array=Hello&some_
74 array=World" will yield the following result:
75
76 { "some_string": "this_is_my_string", "some_array": ["Hello", "World"] }
77
78METHODS EXPORTED TO YOUR API
79 None.
80
81METHODS REQUIRED BY MCBAIN
82 init( $target )
83 Makes the root topic of your API inherit Plack::Component, so that it
84 officially becomes a Plack app. This will provide your API with the
85 "to_app()" method.
86
87 generate_env( $psgi_env )
88 Receives the PSGI env hash-ref and creates McBain's standard env
89 hash-ref from it.
90
91 generate_res( $env, $res )
92 Converts the result of an API method to JSON, and returns a standard
93 PSGI response array-ref.
94
95 handle_exception( $err )
96 Formats exceptions into JSON and returns a standard PSGI array-ref.
97
98CONFIGURATION AND ENVIRONMENT
99 No configuration files are required.
100
101DEPENDENCIES
102 "McBain::WithPSGI" depends on the following CPAN modules:
103
104 * Carp
105
106 * JSON::MaybeXS
107
108 * Plack
109
110INCOMPATIBILITIES WITH OTHER MODULES
111 None reported.
112
113BUGS AND LIMITATIONS
114 Please report any bugs or feature requests to
115 "bug-McBain-WithPSGI@rt.cpan.org", or through the web interface at
116 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=McBain-WithPSGI>.
117
118SUPPORT
119 You can find documentation for this module with the perldoc command.
120
121 perldoc McBain::WithPSGI
122
123 You can also look for information at:
124
125 * RT: CPAN's request tracker
126
127 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=McBain-WithPSGI>
128
129 * AnnoCPAN: Annotated CPAN documentation
130
131 <http://annocpan.org/dist/McBain-WithPSGI>
132
133 * CPAN Ratings
134
135 <http://cpanratings.perl.org/d/McBain-WithPSGI>
136
137 * Search CPAN
138
139 <http://search.cpan.org/dist/McBain-WithPSGI/>
140
141AUTHOR
142 Ido Perlmuter <ido@ido50.net>
143
144LICENSE AND COPYRIGHT
145 Copyright (c) 2013-2015, Ido Perlmuter "ido@ido50.net".
146
147 This module is free software; you can redistribute it and/or modify it
148 under the same terms as Perl itself, either version 5.8.1 or any later
149 version. See perlartistic and perlgpl.
150
151 The full text of the license can be found in the LICENSE file included
152 with this module.
153
154DISCLAIMER OF WARRANTY
155 BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
156 FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
157 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
158 PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
159 EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
160 WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
161 ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
162 YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
163 NECESSARY SERVICING, REPAIR, OR CORRECTION.
164
165 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
166 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
167 REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE
168 TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR
169 CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
170 SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
171 RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
172 FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
173 SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
174 DAMAGES.
175
176