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.