NAME
App::Dochazka::REST::Resource - HTTP request/response cycle
VERSION
Version 0.173
SYNOPSIS
In PSGI file:
use Web::Machine;
Web::Machine->new(
resource => 'App::Dochazka::REST::Resource',
)->to_app;DESCRIPTION
This is where we override the default versions of various methods defined by our "highway to H.A.T.E.O.S.": Web::Machine. (Methods not defined in this module will be inherited from Web::Machine::Resource.)
Do note, however, that none of the routines in this module are called by App::Dochazka::REST.
PACKAGE VARIABLES
METHODS
service_available
This is the first method called on every incoming request.
content_types_provided
Web::Machine calls this routine to determine how to generate the response body for GET requests. It is not called for PUT requests.
_render_response_html
Normally, clients will communicate with the server via '_render_response_json', but humans need HTML. This method takes the server's JSON response and wraps it up in a nice package.
_render_response_json
Encode the context as a JSON string. Wrapper for '_make_json', which is also used in '_render_response_html'.
content_types_accepted
Web::Machine calls this routine to determine how to handle the request body (e.g. in PUT requests).
_handle_request_json
PUT requests may contain a request body. This is the "handler function" where we process those requests.
charsets_provided
This method causes Web::Machine to encode the response body in UTF-8.
default_charset
Really use UTF-8 all the time.
allowed_methods
Determines which HTTP methods we recognize.
uri_too_long
Is the URI too long?
is_authorized
Authentication method.
Authenticate the originator of the request, using HTTP Basic Authentication. Upon successful authentication, check that the user (employee) exists in the database (create if necessary) and retrieve her EID. Push the EID and current privilege level onto the context.
_init_session
Initialize the session. Takes an employee object.
_validate_session
Validate the session
_is_fresh
Takes a single argument, which is assumed to be number of seconds since epoch when the session was last seen. This is compared to "now" and if the difference is greater than the DOCHAZKA_REST_SESSION_EXPIRATION_TIME site parameter, the return value is false, otherwise true.
_authenticate
Authenticate the nick associated with an incoming REST request. Takes a nick and a password (i.e., a set of credentials). Returns a status object, which will have level 'OK' on success (with employee object in the payload), 'NOT_OK' on failure.
forbidden
Authorization (ACL check) method.
First, parse the path and look at the method to determine which controller action the user is asking us to perform. Each controller action has an ACL associated with it, from which we can determine whether employees of each of the four different privilege levels are authorized to perform that action.
Requests for non-existent resources will always pass the ACL check.
If the request passes the ACL check, the mapping (if any) is pushed onto the context for use in the "resource_exists" routine which actually runs the action.
resource_exists
If the resource exists, its mapping will have been determined in the "forbidden" routine. So, our job here is to execute the appropriate target if the mapping exists. Executing the target builds the response entity.
known_content_type
Looks at the 'Content-Type' header of POST and PUT requests, and generates a "415 Unsupported Media Type" response if it is anything other than 'application/json'.
malformed_request
This test examines the request body. It can either be empty or contain valid JSON; otherwise, a '400 Malformed Request' response is returned. If it contains valid JSON, it is converted into a Perl hashref and stored in the 'request_body' attribute of the context.
process_post
Where POST requests are processed.
context
This method is where we store data that needs to be shared among various "users" of the given object (i.e. among routines in this module).
_push_onto_context
Takes a hashref and "pushes" it onto $self->{'context'} for use later on in the course of processing the request.
_make_json
Makes the JSON for inclusion in the response entity.
router
Takes one parameter -- an HTTP method (e.g. 'GET', 'POST'). Returns the router instance for that method, which is stored in a package variable.
init_router
Takes HTTP method and initializes the corresponding router.