Commit | Line | Data |
01f9819a |
1 | NAME |
2 | Catalyst::Controller::REST - A RESTful controller |
3 | |
4 | SYNOPSIS |
5 | package Foo::Controller::Bar; |
6 | |
7 | use base 'Catalyst::Controller::REST'; |
8 | |
9 | sub thing : Local : ActionClass('REST') { } |
10 | |
11 | # Answer GET requests to "thing" |
12 | sub thing_GET { |
13 | my ( $self, $c ) = @_; |
14 | |
15 | # Return a 200 OK, with the data in entity |
16 | # serialized in the body |
17 | $self->status_ok( |
18 | $c, |
19 | entity => { |
20 | some => 'data', |
21 | foo => 'is real bar-y', |
22 | }, |
23 | ); |
24 | } |
25 | |
26 | # Answer PUT requests to "thing" |
27 | sub thing_PUT { |
28 | .. some action .. |
29 | } |
30 | |
31 | DESCRIPTION |
32 | Catalyst::Controller::REST implements a mechanism for building RESTful |
33 | services in Catalyst. It does this by extending the normal Catalyst |
34 | dispatch mechanism to allow for different subroutines to be called based |
35 | on the HTTP Method requested, while also transparently handling all the |
36 | serialization/deserialization for you. |
37 | |
38 | This is probably best served by an example. In the above controller, we |
39 | have declared a Local Catalyst action on "sub thing", and have used the |
40 | ActionClass('REST'). |
41 | |
42 | Below, we have declared "thing_GET" and "thing_PUT". Any GET requests to |
43 | thing will be dispatched to "thing_GET", while any PUT requests will be |
44 | dispatched to "thing_PUT". |
45 | |
46 | Any unimplemented HTTP METHODS will be met with a "405 Method Not |
47 | Allowed" response, automatically containing the proper list of available |
48 | methods. |
49 | |
50 | The HTTP POST, PUT, and OPTIONS methods will all automatically |
51 | deserialize the contents of $c->request->body based on the requests |
52 | content-type header. A list of understood serialization formats is |
53 | below. |
54 | |
55 | Also included in this class are several helper methods, which will |
56 | automatically handle setting up proper response objects for you. |
57 | |
58 | To make your Controller RESTful, simply have it |
59 | |
60 | use base 'Catalyst::Controller::REST'; |
61 | |
62 | SERIALIZATION |
63 | Catalyst::Controller::REST will automatically serialize your responses. |
64 | The currently implemented serialization formats are: |
65 | |
66 | text/x-yaml -> YAML::Syck |
67 | text/x-data-dumper -> Data::Serializer |
68 | |
69 | By default, Catalyst::Controller::REST will use YAML as the |
70 | serialization format. |
71 | |
72 | Implementing new Serialization formats is easy! Contributions are most |
73 | welcome! See Catalyst::Action::Serialize and |
74 | Catalyst::Action::Deserialize for more information. |
75 | |
76 | STATUS HELPERS |
77 | These helpers try and conform to the HTTP 1.1 Specification. You can |
78 | refer to it at: http://www.w3.org/Protocols/rfc2616/rfc2616.txt. These |
79 | routines are all implemented as regular subroutines, and as such require |
80 | you pass the current context ($c) as the first argument. |
81 | |
82 | status_ok |
83 | Returns a "200 OK" response. Takes an "entity" to serialize. |
84 | |
85 | Example: |
86 | |
87 | $self->status_ok( |
88 | $c, |
89 | entity => { |
90 | radiohead => "Is a good band!", |
91 | } |
92 | ); |
93 | |
94 | status_created |
95 | Returns a "201 CREATED" response. Takes an "entity" to serialize, |
96 | and a "location" where the created object can be found. |
97 | |
98 | Example: |
99 | |
100 | $self->status_created( |
101 | $c, |
102 | location => $c->req->uri->as_string, |
103 | entity => { |
104 | radiohead => "Is a good band!", |
105 | } |
106 | ); |
107 | |
108 | In the above example, we use the requested URI as our location. This |
109 | is probably what you want for most PUT requests. |
110 | |
111 | status_accepted |
112 | Returns a "202 ACCEPTED" response. Takes an "entity" to serialize. |
113 | |
114 | Example: |
115 | |
116 | $self->status_accepted( |
117 | $c, |
118 | entity => { |
119 | status => "queued", |
120 | } |
121 | ); |
122 | |
123 | status_bad_request |
124 | Returns a "400 BAD REQUEST" response. Takes a "message" argument as |
125 | a scalar, which will become the value of "error" in the serialized |
126 | response. |
127 | |
128 | Example: |
129 | |
130 | $self->status_bad_request( |
131 | $c, |
132 | entity => { |
133 | message => "Cannot do what you have asked!", |
134 | } |
135 | ); |
136 | |
137 | status_not_found |
138 | Returns a "404 NOT FOUND" response. Takes a "message" argument as a |
139 | scalar, which will become the value of "error" in the serialized |
140 | response. |
141 | |
142 | Example: |
143 | |
144 | $self->status_not_found( |
145 | $c, |
146 | entity => { |
147 | message => "Cannot find what you were looking for!", |
148 | } |
149 | ); |
150 | |
151 | MANUAL RESPONSES |
152 | If you want to construct your responses yourself, all you need to do is |
153 | put the object you want serialized in $c->stash->{'rest'}. |
154 | |
155 | SEE ALSO |
156 | Catalyst::Action::REST, Catalyst::Action::Serialize, |
157 | Catalyst::Action::Deserialize |
158 | |
159 | For help with REST in general: |
160 | |
161 | The HTTP 1.1 Spec is required reading. |
162 | http://www.w3.org/Protocols/rfc2616/rfc2616.txt |
163 | |
164 | Wikipedia! http://en.wikipedia.org/wiki/Representational_State_Transfer |
165 | |
166 | The REST Wiki: http://rest.blueoxen.net/cgi-bin/wiki.pl?FrontPage |
167 | |
168 | AUTHOR |
169 | Adam Jacob <adam@stalecoffee.org>, with lots of help from mst and |
170 | jrockway |
171 | |
172 | Marchex, Inc. paid me while I developed this module. |
173 | (http://www.marchex.com) |
174 | |
175 | LICENSE |
176 | You may distribute this code under the same terms as Perl itself. |
177 | |