[Catalyst-commits] r12405 -
trunk/examples/CatalystAdvent/root/2009/pen
hbrandenburg at dev.catalyst.perl.org
hbrandenburg at dev.catalyst.perl.org
Wed Dec 16 19:59:57 GMT 2009
Author: hbrandenburg
Date: 2009-12-16 19:59:57 +0000 (Wed, 16 Dec 2009)
New Revision: 12405
Modified:
trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod
Log:
copy edits
Modified: trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod 2009-12-16 18:10:15 UTC (rev 12404)
+++ trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod 2009-12-16 19:59:57 UTC (rev 12405)
@@ -2,20 +2,21 @@
=head2 What is REST
-REST means REpresentational State Transfer. The REST approach is to use the
-HTTP verbs (GET, PUT, POST, DELETE) to interact with a webservice; the content
-type of the request to determine the format of the response; and to map the
-URI to a resource. This can be represented by this simple query:
+REST means REpresentational State Transfer. The REST approach is using
+the HTTP verbs (GET, PUT, POST, DELETE) to interact with a webservice,
+using the content type of the request to determine the format of the
+response and then mapping the URI to a resource. Look at this simple
+query:
curl -X GET -H "Content-type: application/json" http://baseuri/book/1
-The query ask (GET) for the book (the ressource) with the id 1, and want the
-response (the content-type) in JSON.
+The query asks (GET) for the book (the resource) with the id of 1, and
+wants the response (C<Content-type>) in JSON.
-=head2 Using of Catalyst::Action::REST
+=head2 Using Catalyst::Action::REST
-The Catalyst::Action::REST module is here to help us to easily create REST
-webserivce in Catalyst.
+The L<Catalyst::Action::REST> module helps us easily create REST
+webservices in Catalyst.
=head3 HTTP Verbs
@@ -23,21 +24,21 @@
sub book : Local : ActionClass('REST') { }
-Then the subroutines for the method you want to handle for that resource:
+Then subroutines for the methods you want to handle that resource:
- sub book_GET {
- }
+ sub book_GET { }
- sub book_POST {
- }
+ sub book_POST { }
-The first method will be executed each time you call the "book" resource,
-whatever the HTTP method is. Catalyst will now dispatch to the subroutine that
-have the appropriate name. So, when you call GET on the resource /book/, first
-it will go through the book subroutine, then the book_GET subroutine. If an id
-is always required to access the book resource (for GET and POST), you can put
-some code to check this in the book sub:
+Catalyst dispatches to the subroutine with the apropriate name. The
+book() subroutine will be executed each time you request the book
+resource, whatever the HTTP method is. For example, when you call GET
+on /book/, first Catalyst goes to the book subroutine,
+then the book_GET subroutine.
+If an ID is required to access the book resource, check for it in
+book():
+
sub book : Local : ActionClass('REST') {
my ($self, $c, $id) = @_;
if (!$id) {
@@ -46,86 +47,87 @@
}
}
-Then book_GET and book_POST subroutines will never be called if the argument id
-is missing.
+Now if C<$id> is missing book_GET() and book_POST() will not be
+called.
=head3 Serialization
-One of the best feature of this module, it's that it handle all the
-serialization/deserialization part for you. You don't need to know how the
-response have to be serialized before sending back to the client, or how the
-data sent to you were serilazed.
+A nice feature of L<Catalyst::Action::REST> is automatic serialization
+and deserialization. You don't need to serialize the response, or know
+how the data sent to you were serialized. When a client makes a
+request, L<Catalyst::Action::REST> attempts to find the appropriate
+content-type for the query. It looks for:
-When a client make a request, Catalyst::Action::REST will try to find the
-appropriate content-type for this query from:
-
=over 4
-=item B<content-type from the HTTP request>
+=item B<Content-type from the HTTP request header>
-It tries to find in the HTTP header of the request the content-type. This
-value can be set like this:
+It tries to find the C<Content-type> of the request in the in the HTTP
+header. This value can be set:
my $req = HTTP::Request(GET => 'http://...');
$req->header('Content-Type' => 'application/json');
-=item B<content-type from the parameter>
+=item B<Content-type from the HTTP request parameter>
-If the content-type is not found using the HTTP::Request, it will check the
-content-type parameter:
+For GET requests, L<Catalyst::Action::REST> also checks the query's
+C<Content-type> parameter:
http://www.example.com/book/id?content-type=application/json
-This is nice, because you can do a request for a specific content type from
-your browser, without needing to change the content-type value from the
+This is nice, because you can do a request for a specific content-type
+from your browser, without changing the content-type value of the
header.
=item B<Accept-Content from the HTTP::Request>
-Finaly, if nothing is found, it will extract the value from the Accept-Content
-from the HTTP request.
+Finally if nothing is found, L<Catalyst::Action::REST> extracts
+content-type from Accept-Content in the HTTP request.
=back
=head3 HTTP Helpers
-Catalyst::Action::REST comes with many helper to generate the appropriate HTTP
-response to a query. When you receive a POST query, and you create a new entry
-from this, you can use the C<status_created> helper, that will generate an
-HTTP response with a code HTTP code 201. If a request got no record, you can
-use the C<status_bad_request> to return a 404.
+L<Catalyst::Action::REST> comes with helpers to generate the
+appropriate HTTP response to a query. When you receive a POST query
+and you create a new entry, you can use the C<status_created> helper,
+to generate an HTTP response with code 201. If a request
+returned no record, you can use C<status_bad_request> to return a 404.
=head3 Configuration
-You can use Catalyst::Action::REST without doing any specific configuration.
-But you can easily customize most of it's parts. When you do
-C<$self->status_ok($c, entity => {foo => 'bar'})>, the content of entity will
-be set in the 'rest' key of the stash. You can change the name of this key:
+L<Catalyst::Action::REST> is usable without any configuration. You can
+also customize many of its parts. When you
+ $self->status_ok($c, entity => {foo => 'bar'});
+
+the content of entity will be set in the 'rest' key of the stash. You
+can change the name of this key:
+
__PACKAGE__->config('stash_key' => 'my_rest_key');
-By default, various serialisations are supported (JSON, YAML, but also
-storable, XML, ...). You may want to limit only some format for your
-application:
+Various serializations are supported: JSON, YAML, storable, XML,
+etc. You might want to limit your application to a subset of these
+formats.
__PACKAGE__->config(map => {
'text/x-yaml' => 'YAML',
'application/json' => 'JSON',
});
-It's also possible to force a default serializer. If no serializer is found
-for a requested content-type, this is the one that will be used.
+It is possible to force a default serializer. If no serializer is found
+for a requested content-type, this one is used:
__PACKAGE__->config('default' => 'application/json');
=head2 Writing a simple controller
-You have a nice website with a database, and you want to provides to your user
-an easy way to access some data.
+Imagine you have a nice website with a database, and you want to
+provide users an easy way to access data.
package BookStore::Controller::API::REST;
use Moose;
- BEGIN { extends 'Catalyst::Controller::REST' };
+ BEGIN { extends 'Catalyst::Controller::REST'};
sub book : Local : ActionClass('REST') { }
@@ -136,9 +138,12 @@
$c->detach();
}
- # do something clever
- my $book = ... $self->status_ok( $c,
- entity => { author => $book->author, title => $book->title } );
+ # do something clever
+ my $book = ...
+ $self->status_ok(
+ $c,
+ entity => { author => $book->author, title => $book->title }
+ );
}
sub book_POST {
More information about the Catalyst-commits
mailing list