table of contents
Web::MREST::Resource(3pm) | User Contributed Perl Documentation | Web::MREST::Resource(3pm) |
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.
2022-09-21 | perl v5.34.0 |