App::MREST::Resource - HTTP request/response cycle
In YourApp/Resource.pm:
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
YourApp::Resource -> Web::MREST::Resource -> Web::Machine::Resource -> Plack::Component
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 for manipulating the context, a hash where we accumulate information about the request.
Constructor/accessor
Takes a hashref and "pushes" it onto $self->{'context'} for use later on in the course of processing the request.
$self->{'context'}
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.
declared_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):
http_code
App::CELL::Status level, can be any of the strings accepted by that module. Defaults to 'ERR'.
The HTTP status code to be applied to the response. Include this only if you need to override the code set by Web::Machine.
Text explaining the status - use this to comply with RFC2616. Defaults to '<NONE>'.
Boolean value for error statuses, specifies whether or not the error is permanent - use this to comply with RFC2616. Defaults to true.
Accessor method, gets just the HTTP status code (might be undef); and allows setting the HTTP status code, as well, by providing an argument.
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.
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.
$self->context->{'declared_status'}
Synonym for status_declared
status_declared
This method nullifies any declared status that might be pending.
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).
This is the first method called on every incoming request.
Hook. If you overlay this and intend to return false, you should call $self->mrest_declare_status !!
$self->mrest_declare_status
Returns the value of MREST_SUPPORTED_HTTP_METHODS site parameter
MREST_SUPPORTED_HTTP_METHODS
Is the URI too long?
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.
A true return value from this method aborts the FSM and triggers a "400 Bad Request" response status.
Hook
Authentication method - should be implemented in the application.
Authorization method - should be implemented in the application.
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.
Content-*
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.
PUT
POST
Content-Type
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.
$site->MREST_SUPPORTED_CONTENT_TYPES
Called by Web::Machine with one argument: the length of the request body. Return true or false.
This method causes Web::Machine to encode the response body (if any) in UTF-8.
See Web::MREST::Entity.
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.
allowed_methods
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.
mrest_resource_exists
For GET and POST, failure means 404 by default, but can be overrided by calling mrest_declare_status from within mrest_resource_exists.
mrest_declare_status
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.
If the application wishes to allow POST to a non-existent resource, this method will need to be overrided.
Looks for a 'post_is_create' property in the context and returns 1 or 0, as appropriate.
This should always return _something_ (never undef)
This is set to true so we can set $self->context->{'create_path'} in the handler.
$self->context->{'create_path'}
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.
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).
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.
To install Web::MREST, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Web::MREST
CPAN shell
perl -MCPAN -e shell install Web::MREST
For more information on module installation, please visit the detailed CPAN module installation guide.