Provided by: libweb-mrest-perl_0.290-1_all 
NAME
App::MREST::Resource - HTTP request/response cycle
SYNOPSIS
In "YourApp/Resource.pm":
use parent 'Web::MREST::Resource';
In PSGI file:
use Web::Machine;
Web::Machine->new(
resource => 'App::YourApp::Resource',
)->to_app;
It is important to understand that the Web::Machine object created is actually blessed
into "YourApp::Resource". The line of inheritance is:
YourApp::Resource
-> Web::MREST::Resource
-> Web::Machine::Resource
-> Plack::Component
DESCRIPTION
Your application should not call any of the routines in this module directly. They are
called by Web::Machine during the course of request processing. What your application can
do is provide its own versions of selected routines.
METHODS
Context methods
Methods for manipulating the context, a hash where we accumulate information about the
request.
context
Constructor/accessor
push_onto_context
Takes a hashref and "pushes" it onto "$self->{'context'}" for use later on in the course
of processing the request.
Status declaration methods
Although Web::Machine takes care of setting the HTTP response status code, but when we
have to override Web::Machine's value we have this "MREST declared status" mechanism,
which places a "declared_status" property in the context. During finalization, the HTTP
status code placed in this property overrides the one Web::Machine came up with.
mrest_declare_status
This method takes either a ready-made App::CELL::Status object or, alternatively, a
PARAMHASH. In the former case, an HTTP status code can be "forced" on the response by
including a "http_code" property in the object. In the latter case, the following keys are
recognized (and all of them are optional):
level
App::CELL::Status level, can be any of the strings accepted by that module. Defaults
to 'ERR'.
code
The HTTP status code to be applied to the response. Include this only if you need to
override the code set by Web::Machine.
explanation
Text explaining the status - use this to comply with RFC2616. Defaults to '<NONE>'.
permanent
Boolean value for error statuses, specifies whether or not the error is permanent -
use this to comply with RFC2616. Defaults to true.
mrest_declared_status_code
Accessor method, gets just the HTTP status code (might be undef); and allows setting the
HTTP status code, as well, by providing an argument.
mrest_declared_status_explanation
Accessor method, gets just the explanation (might be undef). Does not allow changing the
explanation - for this, nullify the declared status and declare a new one.
status_declared
Boolean method - checks context for presence of 'declared_status' property. If it is
present, the value of that property is returned, just as if we had done
"$self->context->{'declared_status'}". Otherwise, undef (false) is returned.
declared_status
Synonym for "status_declared"
nullify_declared_status
This method nullifies any declared status that might be pending.
FSM Part One
The following methods override methods defined by Web::Machine::Resource. They correspond
to what the Web::MREST calls "Part One" of the FSM. To muffle debug-level log messages
from this part of the FSM, set $muffle{1} = 1 (above).
service_available (B13)
This is the first method called on every incoming request.
mrest_service_available
Hook. If you overlay this and intend to return false, you should call
"$self->mrest_declare_status" !!
known_methods (B12)
Returns the value of "MREST_SUPPORTED_HTTP_METHODS" site parameter
uri_too_long (B11)
Is the URI too long?
allowed_methods (B10)
Determines which HTTP methods we recognize for this resource. We return these methods in
an array. If the requested method is not included in the array, Web::Machine will return
the appropriate HTTP error code.
RFC2616 on 405: "The response MUST include an Allow header containing a list of valid
methods for the requested resource." -> this is handled by Web::Machine, but be aware that
if the methods arrayref returned by allowed_methods does not include the current request
method, allow_methods gets called again.
malformed_request (B9)
A true return value from this method aborts the FSM and triggers a "400 Bad Request"
response status.
mrest_malformed_request
Hook
is_authorized (B8)
Authentication method - should be implemented in the application.
forbidden (B7)
Authorization method - should be implemented in the application.
valid_content_headers (B6)
Receives a Hash::MultiValue object containing all the "Content-*" headers in the request.
Checks these against << $site->MREST_VALID_CONTENT_HEADERS >>, returns false if the check
fails, true if it passes.
known_content_type (B5)
The assumption for "PUT" and "POST" requests is that they might have an accompanying
request entity, the type of which should be declared via a "Content-Type" header. If the
content type is not recognized by the application, return false from this method to
trigger a "415 Unsupported Media Type" response.
The basic content-types (major portions only) accepted by the application should be listed
in "$site->MREST_SUPPORTED_CONTENT_TYPES". Override this method if that's not good by you.
valid_entity_length (B4)
Called by Web::Machine with one argument: the length of the request body. Return true or
false.
charsets_provided
This method causes Web::Machine to encode the response body (if any) in UTF-8.
FSM Part Two (Content Negotiation)
See Web::MREST::Entity.
FSM Part Three (Resource Existence)
resource_exists (G7)
The initial check for resource existence is the URI-to-resource mapping, which has already
taken place in "allowed_methods". Having made it to here, we know that was successful.
So, what we do here is call the handler function, which is expected to return an
App::CELL::Status object. How this status is interpreted is left up to the application: we
pass the status object to the "mrest_resource_exists" method, which should return either
true or false.
For GET and POST, failure means 404 by default, but can be overrided by calling
"mrest_declare_status" from within "mrest_resource_exists".
For PUT, success means this is an update operation and failure means insert.
For DELETE, failure means "202 Accepted" - i.e. a request to delete a resource that
doesn't exist is accepted, but nothing actually happens.
allow_missing_post
If the application wishes to allow POST to a non-existent resource, this method will need
to be overrided.
post_is_create
mrest_post_is_create
Looks for a 'post_is_create' property in the context and returns 1 or 0, as appropriate.
create_path
mrest_create_path
This should always return _something_ (never undef)
create_path_after_handler
This is set to true so we can set "$self->context->{'create_path'}" in the handler.
process_post
This is where we construct responses to POST requests that do not create a new resource.
Since we expect our resource handlers to "do the needful", all we need to do is call the
resource handler for pass two.
The return value should be a Web::Machine/HTTP status code like, e.g., \200 - this ensures
that Web::Machine does not attempt to encode the response body, as in our case this would
introduce a double- encoding bug.
delete_resource
This method is called on DELETE requests and is supposed to tell Web::Machine whether or
not the DELETE operation was enacted. In our case, we call the resource handler (pass
two).
finish_request
This overrides the Web::Machine method of the same name, and is called just before the
final response is constructed and sent. We use it for adding certain headers in every
response.