X-Git-Url: http://git.rot13.org/?a=blobdiff_plain;f=C4%2FService.pm;h=d9990ff90743f6a79fdda32267ebaec3e575ee16;hb=08382876306cfda839637c5f72a107b304458a8e;hp=641ab2f3e8282ffbfc4008730a115263bc6e306e;hpb=b04f432857617c6a7b3333863e34420103321ea1;p=koha.git

diff --git a/C4/Service.pm b/C4/Service.pm
index 641ab2f3e8..d9990ff907 100644
--- a/C4/Service.pm
+++ b/C4/Service.pm
@@ -13,9 +13,9 @@ package C4::Service;
 # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
 # A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 #
-# You should have received a copy of the GNU General Public License along with
-# Koha; if not, write to the Free Software Foundation, Inc., 59 Temple Place,
-# Suite 330, Boston, MA  02111-1307 USA
+# You should have received a copy of the GNU General Public License along
+# with Koha; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 =head1 NAME
 
@@ -59,11 +59,7 @@ our ( $query, $cookie );
 
 =head2 init
 
-=over 4
-
-    our ( $query, $response ) = C4::Service->init( %needed_flags );
-
-=back
+   our ( $query, $response ) = C4::Service->init( %needed_flags );
 
 Initialize the service and check for the permissions in C<%needed_flags>.
 
@@ -85,19 +81,15 @@ sub init {
 
     our $cookie = $cookie_; # I have no desire to offend the Perl scoping gods
 
-    $class->return_error( type => 'auth', message => $status ) if ( $status ne 'ok' );
+    $class->return_error( 'auth', $status ) if ( $status ne 'ok' );
 
     return ( $query, new C4::Output::JSONStream );
 }
 
 =head2 return_error
 
-=over 4
-
     C4::Service->return_error( $type, $error, %flags );
 
-=back
-
 Exit the script with HTTP status 400, and return a JSON error object.
 
 C<$type> should be a short, lower case code for the generic type of error (such
@@ -125,24 +117,16 @@ sub return_error {
     exit;
 }
 
-=head return_multi
+=head2 return_multi
 
-=over 4
-
-C4::Service->return_multi( \@responses, %flags );
-
-=back
+    C4::Service->return_multi( \@responses, %flags );
 
 return_multi is similar to return_success or return_error, but allows you to
 return different statuses for several requests sent at once (using HTTP status
 "207 Multi-Status", much like WebDAV). The toplevel hashref (turned into the
 JSON response) looks something like this:
 
-=over 4
-
-{ multi => JSON::true, responses => \@responses, %flags }
-
-=back
+    { multi => JSON::true, responses => \@responses, %flags }
 
 Each element of @responses should be either a plain hashref or an arrayref. If
 it is a hashref, it is sent to the browser as-is. If it is an arrayref, it is
@@ -183,12 +167,8 @@ sub return_multi {
 
 =head2 return_success
 
-=over 4
-
     C4::Service->return_success( $response );
 
-=back
-
 Print out the information in the C<C4::Output::JSONStream> C<$response>, then
 exit with HTTP status 200.
 
@@ -202,12 +182,8 @@ sub return_success {
 
 =head2 require_params
 
-=over 4
-
     my @values = C4::Service->require_params( @params );
 
-=back
-
 Check that each of of the parameters specified in @params was sent in the
 request, then return their values in that order.
 
@@ -228,23 +204,21 @@ sub require_params {
     return @values;
 }
 
-=head dispatch
-
-=over 4
-
-C4::Service->dispatch(
-    [ $path_regex, \@required_params, \&handler ],
-    ...
-);
+=head2 dispatch
 
-=back
+    C4::Service->dispatch(
+        [ $path_regex, \@required_params, \&handler ],
+        ...
+    );
 
 dispatch takes several array-refs, each one describing a 'route', to use the
 Rails terminology.
 
-$path_regex should be a string in regex-form, describing which paths this route
-handles. Each route is tested in order, from the top down, so put more specific
-handlers first. Also, the regex is tested on the entire path.
+$path_regex should be a string in regex-form, describing which methods and
+paths this route handles. Each route is tested in order, from the top down, so
+put more specific handlers first. Also, the regex is tested on the request
+method, plus the path. For instance, you might use the route [ 'POST /', ... ]
+to handle POST requests to your service.
 
 Each named parameter in @required_params is tested for to make sure the route
 matches, but does not raise an error if one is missing; it simply tests the next
@@ -253,7 +227,7 @@ C<C4::Service->require_params> inside your handler.
 
 \&handler is called with each matched group in $path_regex in its arguments. For
 example, if your service is accessed at the path /blah/123, and you call
-C<dispatch> with the route [ '/blah/(\\d+)', ... ], your handler will be called
+C<dispatch> with the route [ 'GET /blah/(\\d+)', ... ], your handler will be called
 with the argument '123'.
 
 =cut