view release on metacpan or  search on metacpan

lib/App/Dochazka/REST/ResourceDefs.pm  view on Meta::CPAN

=pod

Enables existing interval objects to be updated by sending a POST request to
the REST server. Along with the properties to be modified, the request body
must include an 'iid' property, the value of which specifies the iid to be
updated.
EOH
    },

    # /interval/iid/:iid
    'interval/iid/:iid' => 
    {
        parent => 'interval',
        handler => {
            GET => 'handler_get_interval_iid',
            PUT => 'handler_interval_iid',
            DELETE => 'handler_interval_iid',
        },
        acl_profile => {
            GET => 'inactive',
            PUT => 'active',
            DELETE => 'active',
        },
        cli => 'interval iid $iid [$JSON]',
        validations => {
            'iid' => 'Int',
        },
        description => 'GET, PUT, or DELETE an interval object by its iid',
        documentation => <<'EOH',
=pod

This resource makes it possible to GET, PUT, or DELETE an interval object by
its IID.

=over

=item * GET

Retrieves an interval object by its IID.

=item * PUT

Updates the interval object whose iid is specified by the ':iid' URI parameter.
The fields to be updated and their new values should be sent in the request
body, e.g., like this:

    { 
        "eid" : 34, 
        "aid" : 1, 
        "intvl" : '[ 2014-11-18 08:00, 2014-11-18 12:00 )' 
    }

=item * DELETE

Deletes the interval object whose iid is specified by the ':iid' URI parameter.
As long as the interval does not overlap with a lock interval, the delete operation
will probably work as expected.

=back

ACL note: 'active' employees can update/delete only their own unlocked intervals.
EOH
    },

    # /interval/new
    'interval/new' => 
    {
        parent => 'interval',
        handler => {
            POST => 'handler_interval_new',
        },
        acl_profile => 'active', 
        cli => 'interval new $JSON',
        description => 'Add a new attendance data interval',
        documentation => <<'EOH',
=pod

This is the resource by which employees add new attendance data to the
database. It takes a request body containing, at the very least, C<aid> and
C<intvl> properties. Additionally, it can contain C<long_desc>, while
administrators can also specify C<eid> and C<remark>.
EOH
    },

    # /interval/nick/:nick/:tsrange
    'interval/nick/:nick/:tsrange' => 
    {
        parent => 'interval',
        handler => {
            GET => 'handler_interval_nick',
            DELETE => 'handler_interval_nick',
        },
        acl_profile => {
            GET => 'inactive', 
            DELETE => 'active',
        },
        cli => 'interval nick $NICK $TSRANGE',
        validations => {
            'nick' => $term_validation,
            'tsrange' => $tsrange_validation,
        },
        description => 'Retrieve an arbitrary employee\'s intervals over the given tsrange',
        documentation => <<'EOH',
=pod

With this resource, administrators can retrieve any employee's intervals 
over a given tsrange, and active employees can do the same with their own intervals. 

Before any records are returned, the tsrange is checked to see if it overlaps with
any privlevel or schedule changes - in which case an error is returned. This is so
interval report-generators do not have to handle changes in employee status.

By default, the number of intervals returned is limited to 500. This number
can be changed via the DOCHAZKA_INTERVAL_SELECT_LIMIT site configuration
parameter (set to 'undef' for no limit).
EOH
    },

    # /interval/nick/:nick/:ts/:psqlint'
    'interval/nick/:nick/:ts/:psqlint' => 
    {

lib/App/Dochazka/REST/ResourceDefs.pm  view on Meta::CPAN

            PUT => 'handler_lock_lid',
            DELETE => 'handler_lock_lid',
        },
        acl_profile => {
            GET => 'active',
            PUT => 'admin',
            DELETE => 'admin',
        },
        cli => 'lock lid $lid [$JSON]',
        validations => {
            'lid' => 'Int',
        },
        description => 'GET, PUT, or DELETE an lock object by its LID',
        documentation => <<'EOH',
=pod

This resource makes it possible to GET, PUT, or DELETE an lock object by its
LID.

=over

=item * GET

Retrieves an lock object by its lid.

=item * PUT

Updates the lock object whose lid is specified by the ':lid' URI parameter.
The fields to be updated and their new values should be sent in the request
body, e.g., like this:

    { 
        "eid" : 34, 
        "intvl" : '[ 2014-11-18 00:00, 2014-11-18 24:00 )' 
    }

=item * DELETE

Deletes the lock object whose lid is specified by the ':lid' URI parameter.

=back

ACL note: 'active' employees can view only their own locks, and of course
admin privilege is required to modify or remove a lock.
EOH
    },
    # /lock/new
    'lock/new' => 
    {
        parent => 'lock',
        handler => {
            POST => 'handler_lock_new',
        },
        acl_profile => 'active', 
        cli => 'lock new $JSON',
        description => 'Add a new attendance data lock',
        documentation => <<'EOH',
=pod

This is the resource by which the attendance data entered by an employee 
for a given time period can be "locked" to prevent any subsequent
modifications.  It takes a request body containing, at the very least, an
C<intvl> property specifying the tsrange to lock. Additionally, administrators
can specify C<remark> and C<eid> properties.
EOH
    },

    # /lock/nick/:nick/:tsrange
    'lock/nick/:nick/:tsrange' => 
    {
        parent => 'lock',
        handler => {
            GET => 'handler_get_lock_nick',
        },
        acl_profile => 'active', 
        cli => 'lock nick $NICK $TSRANGE',
        validations => {
            'nick' => $term_validation,
            'tsrange' => $tsrange_validation,
        },
        description => 'Retrieve an arbitrary employee\'s locks over the given tsrange',
        documentation => <<'EOH',
=pod

With this resource, administrators can retrieve any employee's locks 
over a given tsrange. 

There are no syntactical limitations on the tsrange, but if too many records would
be fetched, the return status will be C<DISPATCH_TOO_MANY_RECORDS_FOUND>.
EOH
    },

    # /lock/self/:tsrange
    'lock/self/:tsrange' => 
    {
        parent => 'lock',
        handler => {
            GET => 'handler_get_lock_self',
        },
        acl_profile => 'inactive', 
        cli => 'lock self $TSRANGE',
        validations => {
            'tsrange' => $tsrange_validation,
        },
        description => 'Retrieve one\'s own locks over the given tsrange',
        documentation => <<'EOH',
=pod

With this resource, employees can retrieve their own attendance locks 
over a given tsrange. 

There are no syntactical limitations on the tsrange, but if too many records would
be fetched, the return status will be C<DISPATCH_TOO_MANY_RECORDS_FOUND>.
EOH
    },

};


=head2 Priv (non-history) resources