[Catalyst-commits] r12432 - in
trunk/examples/CatalystAdvent/root/2009: . pen
zamolxes at dev.catalyst.perl.org
zamolxes at dev.catalyst.perl.org
Sat Dec 19 00:01:09 GMT 2009
Author: zamolxes
Date: 2009-12-19 00:01:06 +0000 (Sat, 19 Dec 2009)
New Revision: 12432
Added:
trunk/examples/CatalystAdvent/root/2009/19.pod
Removed:
trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod
Log:
day 19 franck++
Copied: trunk/examples/CatalystAdvent/root/2009/19.pod (from rev 12431, trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod)
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/19.pod (rev 0)
+++ trunk/examples/CatalystAdvent/root/2009/19.pod 2009-12-19 00:01:06 UTC (rev 12432)
@@ -0,0 +1,186 @@
+=head1 Writing REST web services with Catalyst::Controller::REST
+
+This article is a minor update to the 2006 entry about L<Catalyst::Controller::REST>,
+which can be found at L<http://www.catalystframework.org/calendar/2006/9>.
+
+=head1 What is REST
+
+REST means REpresentational State Transfer. The REST approach is using the
+HTTP verbs (GET, PUT, POST, DELETE) to interact with a web service, 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 asks (GET) for the book (the resource) with the id of 1, and wants
+the response (C<Content-type>) in JSON.
+
+=head1 Using Catalyst::Controller::REST
+
+The L<Catalyst::Controller::REST> module helps us easily create REST web
+services in Catalyst.
+
+=head2 HTTP Verbs
+
+First you declare a new resource:
+
+ sub book : Local : ActionClass('REST') { }
+
+Then subroutines for the methods you want to handle that resource:
+
+ sub book_GET { }
+
+ sub book_POST { }
+
+Catalyst dispatches to the subroutine with the appropriate 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) {
+ $self->status_bad_request($c, message => 'id is missing');
+ $c->detach();
+ }
+ }
+
+Now if C<$id> is missing book_GET() and book_POST() will not be
+called.
+
+=head2 Serialization
+
+A nice feature of L<Catalyst::Controller::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::Controller::REST> attempts to find the appropriate
+content-type for the query. It looks for:
+
+=over 4
+
+=item B<Content-type from the HTTP request header>
+
+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 HTTP request parameter>
+
+For GET requests, L<Catalyst::Controller::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 changing the content-type value of the
+header.
+
+=item B<Accept-Content from the HTTP::Request>
+
+Finally if nothing is found, L<Catalyst::Controller::REST> extracts
+content-type from Accept-Content in the HTTP request.
+
+=back
+
+=head2 HTTP Helpers
+
+L<Catalyst::Controller::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.
+
+=head2 Configuration
+
+L<Catalyst::Controller::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');
+
+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 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');
+
+=head1 Writing a simple controller
+
+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'};
+
+ sub book : Local : ActionClass('REST') { }
+
+ sub book_get {
+ my ( $self, $c, $id ) = @_;
+ if ( !$id ) {
+ $self->status_bad_request( $c, message => "id is missing" );
+ $c->detach();
+ }
+
+ # do something clever
+ my $book = ...
+ $self->status_ok(
+ $c,
+ entity => { author => $book->author, title => $book->title }
+ );
+ }
+
+ sub book_POST {
+ my ( $self, $c ) = @_;
+ my $book_content = $c->req->data;
+ # insert book
+ $self->status_created(
+ $c,
+ location => $c->req->uri->as_string,
+ entity => { title => $book->title, author => $book->author }
+ );
+ }
+
+ sub book_PUT {
+ my ( $self, $c ) = @_;
+ my $new_quantity = $c->req->data->{quantity};
+ # update quantity
+ }
+
+ sub book_DELETE {
+ my ( $self, $c, $id ) = @_;
+ $self->status_accepted( $c, entity => { status => "deleted" } );
+ }
+
+ 1;
+
+=head1 SEE ALSO
+
+L<http://www.catalystframework.org/calendar/2006/9>
+
+L<http://en.wikipedia.org/wiki/REST>
+
+L<http://search.cpan.org/perldoc?Catalyst::Controller::REST>
+
+=head1 Author
+
+Franck Cuny <franck at lumberjaph.net>
+
Deleted: trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod
===================================================================
--- trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod 2009-12-18 19:55:03 UTC (rev 12431)
+++ trunk/examples/CatalystAdvent/root/2009/pen/catalyst-action-rest.pod 2009-12-19 00:01:06 UTC (rev 12432)
@@ -1,186 +0,0 @@
-=head1 Writing REST web services with Catalyst::Controller::REST
-
-This article is a minor update to the 2006 entry about L<Catalyst::Controller::REST>,
-which can be found at L<http://www.catalystframework.org/calendar/2006/9>.
-
-=head1 What is REST
-
-REST means REpresentational State Transfer. The REST approach is using the
-HTTP verbs (GET, PUT, POST, DELETE) to interact with a web service, 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 asks (GET) for the book (the resource) with the id of 1, and wants
-the response (C<Content-type>) in JSON.
-
-=head1 Using Catalyst::Controller::REST
-
-The L<Catalyst::Controller::REST> module helps us easily create REST web
-services in Catalyst.
-
-=head2 HTTP Verbs
-
-First you declare a new resource:
-
- sub book : Local : ActionClass('REST') { }
-
-Then subroutines for the methods you want to handle that resource:
-
- sub book_GET { }
-
- sub book_POST { }
-
-Catalyst dispatches to the subroutine with the appropriate 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) {
- $self->status_bad_request($c, message => 'id is missing');
- $c->detach();
- }
- }
-
-Now if C<$id> is missing book_GET() and book_POST() will not be
-called.
-
-=head2 Serialization
-
-A nice feature of L<Catalyst::Controller::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::Controller::REST> attempts to find the appropriate
-content-type for the query. It looks for:
-
-=over 4
-
-=item B<Content-type from the HTTP request header>
-
-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 HTTP request parameter>
-
-For GET requests, L<Catalyst::Controller::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 changing the content-type value of the
-header.
-
-=item B<Accept-Content from the HTTP::Request>
-
-Finally if nothing is found, L<Catalyst::Controller::REST> extracts
-content-type from Accept-Content in the HTTP request.
-
-=back
-
-=head2 HTTP Helpers
-
-L<Catalyst::Controller::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.
-
-=head2 Configuration
-
-L<Catalyst::Controller::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');
-
-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 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');
-
-=head1 Writing a simple controller
-
-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'};
-
- sub book : Local : ActionClass('REST') { }
-
- sub book_get {
- my ( $self, $c, $id ) = @_;
- if ( !$id ) {
- $self->status_bad_request( $c, message => "id is missing" );
- $c->detach();
- }
-
- # do something clever
- my $book = ...
- $self->status_ok(
- $c,
- entity => { author => $book->author, title => $book->title }
- );
- }
-
- sub book_POST {
- my ( $self, $c ) = @_;
- my $book_content = $c->req->data;
- # insert book
- $self->status_created(
- $c,
- location => $c->req->uri->as_string,
- entity => { title => $book->title, author => $book->author }
- );
- }
-
- sub book_PUT {
- my ( $self, $c ) = @_;
- my $new_quantity = $c->req->data->{quantity};
- # update quantity
- }
-
- sub book_DELETE {
- my ( $self, $c, $id ) = @_;
- $self->status_accepted( $c, entity => { status => "deleted" } );
- }
-
- 1;
-
-=head1 SEE ALSO
-
-L<http://www.catalystframework.org/calendar/2006/9>
-
-L<http://en.wikipedia.org/wiki/REST>
-
-L<http://search.cpan.org/perldoc?Catalyst::Controller::REST>
-
-=head1 Author
-
-Franck Cuny <franck at lumberjaph.net>
-
More information about the Catalyst-commits
mailing list