App-Dochazka-REST
view release on metacpan or search on metacpan
lib/App/Dochazka/REST/ResourceDefs.pm view on Meta::CPAN
=pod
Shows the software version running on the present instance. The version displayed
is taken from the C<$VERSION> package variable of the package specified in the
C<MREST_APPLICATION_MODULE> site parameter.
EOH
},
# /whoami
'whoami' => {
parent => '/',
handler => {
GET => 'handler_whoami',
},
acl_profile => 'passerby',
cli => 'whoami',
description => 'Display the current employee (i.e. the one we authenticated with)',
documentation => <<'EOH',
=pod
Displays the profile of the currently logged-in employee
EOH
},
};
=head2 Activity resources
=cut
$defs->{'activity'} = {
# /activity
'activity' =>
{
parent => '/',
handler => 'handler_noop',
acl_profile => 'passerby',
cli => 'activity',
description => 'Parent for activity resources',
documentation => <<'EOH',
=pod
Parent for activity resources
EOH
},
# /activity/aid
'activity/aid' =>
{
parent => 'activity',
handler => {
POST => 'handler_post_activity_aid',
},
acl_profile => 'admin',
cli => 'activity aid',
description => 'Update an existing activity object via POST request (AID must be included in request body)',
documentation => <<'EOH',
=pod
Enables existing activity 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 'aid' property, the value of which specifies the AID to be
updated.
EOH
},
# /activity/aid/:aid
'activity/aid/:aid' =>
{
parent => 'activity',
handler => {
GET => 'handler_activity_aid',
PUT => 'handler_activity_aid',
DELETE => 'handler_activity_aid',
},
acl_profile => {
GET => 'active',
PUT => 'admin',
DELETE => 'admin',
},
cli => 'activity aid $AID',
validations => {
'aid' => 'Int',
},
description => 'GET, PUT, or DELETE an activity object by its AID',
documentation => <<'EOH',
=pod
This resource allows the user to GET, PUT, or DELETE an activity object by its
AID.
=over
=item * GET
Retrieves an activity object by its AID.
=item * PUT
Updates the activity object whose AID is specified by the ':aid' URI parameter.
The fields to be updated and their new values should be sent in the request
body, e.g., like this:
{ "long_desc" : "new description", "disabled" : "f" }
=item * DELETE
Deletes the activity object whose AID is specified by the ':aid' URI parameter.
This will work only if nothing in the database refers to this activity.
=back
EOH
},
# /activity/all
'activity/all' =>
{
parent => 'activity',
handler => {
GET => 'handler_get_activity_all',
},
acl_profile => 'passerby',
cli => 'activity all',
description => 'Retrieve all activity objects (excluding disabled ones)',
documentation => <<'EOH',
=pod
Retrieves all activity objects in the database (excluding disabled activities).
EOH
},
# /activity/all/disabled
'activity/all/disabled' =>
{
parent => 'activity/all',
handler => {
GET => 'handler_get_activity_all_disabled',
},
acl_profile => 'admin',
cli => 'activity all disabled',
description => 'Retrieve all activity objects, including disabled ones',
documentation => <<'EOH',
=pod
Retrieves all activity objects in the database (including disabled activities).
EOH
},
# /activity/code
'activity/code' =>
{
parent => 'activity',
handler => {
POST => 'handler_post_activity_code',
},
acl_profile => 'admin',
cli => 'activity aid',
description => 'Update an existing activity object via POST request (activity code must be included in request body)',
documentation => <<'EOH',
=pod
This resource enables existing activity objects to be updated, and new
activity objects to be inserted, by sending a POST request to the REST server.
Along with the properties to be modified/inserted, the request body must
include an 'code' property, the value of which specifies the activity to be
updated.
EOH
},
# /activity/code/:code
'activity/code/:code' =>
{
parent => 'activity',
handler => {
GET => 'handler_get_activity_code',
PUT => 'handler_put_activity_code',
DELETE => 'handler_delete_activity_code',
},
acl_profile => {
GET => 'passerby',
PUT => 'admin',
DELETE => 'admin',
},
cli => 'activity code $CODE',
validations => {
'code' => qr/^[[:alnum:]_][[:alnum:]_-]+$/,
},
description => 'GET, PUT, or DELETE an activity object by its code',
documentation => <<'EOH',
=pod
With this resource, a user can GET, PUT, or DELETE an activity object by its
code.
=over
=item * GET
Retrieves an activity object by its code.
=item * PUT
Inserts new or updates existing activity object whose code is specified by the
':code' URI parameter. The fields to be updated and their new values should be
sent in the request body, e.g., like this:
{ "long_desc" : "new description", "disabled" : "f" }
=item * DELETE
Deletes an activity object by its code whose code is specified by the ':code'
URI parameter. This will work only if nothing in the database refers to this
activity.
=back
EOH
},
};
=head2 Component resources
=cut
$defs->{'component'} = {
# /component
'component' =>
{
parent => '/',
handler => 'handler_noop',
acl_profile => 'passerby',
cli => 'component',
description => 'Parent for component resources',
documentation => <<'EOH',
=pod
Parent for component resources
EOH
},
# /component/all
'component/all' =>
{
parent => 'component',
handler => {
GET => 'handler_get_component_all',
},
acl_profile => 'admin',
cli => 'component all',
description => 'Retrieve all component objects',
documentation => <<'EOH',
=pod
Retrieves all component objects in the database.
EOH
},
# /component/cid
'component/cid' =>
{
parent => 'component',
handler => {
POST => 'handler_post_component_cid',
},
acl_profile => 'admin',
cli => 'component cid',
description => 'Update an existing component object via POST request (cid must be included in request body)',
documentation => <<'EOH',
=pod
Enables existing component 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 'cid' property, the value of which specifies the cid to be
updated.
EOH
},
# /component/cid/:cid
'component/cid/:cid' =>
{
parent => 'component',
handler => {
GET => 'handler_component_cid',
PUT => 'handler_component_cid',
DELETE => 'handler_component_cid',
},
acl_profile => 'admin',
cli => 'component cid $cid',
validations => {
'cid' => 'Int',
},
description => 'GET, PUT, or DELETE an component object by its cid',
documentation => <<'EOH',
=pod
This resource allows the user to GET, PUT, or DELETE an component object by its
cid.
=over
=item * GET
Retrieves an component object by its cid.
=item * PUT
Updates the component object whose cid is specified by the ':cid' URI parameter.
The fields to be updated and their new values should be sent in the request
body, e.g., like this:
{ "path" : "new/path", "source" : "new source", "acl" : "inactive" }
=item * DELETE
Deletes the component object whose cid is specified by the ':cid' URI parameter.
This will work only if nothing in the database refers to this component.
=back
EOH
},
# /component/path
'component/path' =>
{
parent => 'component',
handler => {
POST => 'handler_post_component_path',
},
acl_profile => 'admin',
cli => 'component cid',
description => 'Update an existing component object via POST request (component path must be included in request body)',
documentation => <<'EOH',
=pod
This resource enables existing component objects to be updated, and new
component objects to be inserted, by sending a POST request to the REST server.
Along with the properties to be modified/inserted, the request body must
include an 'path' property, the value of which specifies the component to be
updated.
EOH
},
};
=head2 Employee resources
=cut
$defs->{'employee'} = {
# /employee
'employee' =>
{
parent => '/',
handler => 'handler_noop',
acl_profile => 'passerby',
cli => 'employee',
description => 'Parent for employee resources',
documentation => <<'EOH',
=pod
Parent for employee resources
EOH
},
# /employee/count/?:priv
'employee/count/?:priv' =>
{
parent => 'employee',
handler => {
GET => 'handler_get_employee_count',
},
acl_profile => 'admin',
cli => 'employee count',
validations => {
'priv' => $priv_validation,
},
description => 'Display total count of employees (optionally by privlevel)',
documentation => <<'EOH',
=pod
If ':priv' is not specified, gets the total number of employees in the
database. This includes employees of all privilege levels, including not only
administrators and active employees, but inactives and passerbies as well.
If ':priv' is specified, gets the total number of employees with the
given privlevel. Valid privlevels are:
=over
=item * passerby
=item * inactive
=item * active
=item * admin
=back
EOH
},
# /employee/eid
'employee/eid' =>
{
parent => 'employee',
handler => {
POST => 'handler_post_employee_eid',
},
acl_profile => 'inactive',
cli => 'employee eid $JSON',
description => 'Update existing employee (JSON request body with EID required)',
documentation => <<'EOH',
=pod
This resource provides a way to update employee objects using the
POST method, provided the employee's EID is provided in the content body.
The properties to be modified should also be included, e.g.:
{ "eid" : 43, "fullname" : "Foo Bariful" }
This would change the 'fullname' property of the employee with EID 43 to "Foo
Bariful" (provided such an employee exists).
ACL note: 'inactive' and 'active' employees can use this resource to modify
their own employee profile. Exactly which fields can be updated may differ from
site to site (see the DOCHAZKA_PROFILE_EDITABLE_FIELDS site parameter).
EOH
},
# /employee/eid/:eid
'employee/eid/:eid' =>
{
parent => 'employee',
handler => {
GET => 'handler_get_employee_eid',
PUT => 'handler_put_employee_eid',
DELETE => 'handler_delete_employee_eid',
},
acl_profile => {
GET => 'passerby',
PUT => 'inactive',
DELETE => 'admin',
},
cli => 'employee eid $EID [$JSON]',
validations => {
eid => 'Int',
},
description => 'GET: look up employee (exact match); PUT: update existing employee; DELETE: delete employee',
documentation => <<'EOH',
=pod
With this resource, we can look up an employee by exact match (GET),
update an existing employee (PUT), or delete an employee (DELETE).
=over
=item * GET
Retrieves an employee object by its EID.
=item * PUT
Updates the "employee profile" (employee object) of the employee with
the given EID. For example, if the request body was:
{ "fullname" : "Foo Bariful" }
the request would change the 'fullname' property of the employee with EID 43
(provided such an employee exists) to "Foo Bariful". Any 'eid' property
provided in the content body will be ignored.
ACL note: 'inactive' and 'active' employees can use this resource to modify
their own employee profile. Exactly which fields can be updated may differ from
site to site (see the DOCHAZKA_PROFILE_EDITABLE_FIELDS site parameter).
=item * DELETE
Deletes the employee with the given EID (will only work if the EID
exists and nothing in the database refers to it).
=back
EOH
},
# /employee/eid/:eid/full
'employee/eid/:eid/full' =>
{
parent => 'employee/eid/:eid',
handler => {
GET => 'handler_get_employee_eid_full',
},
acl_profile => 'inactive',
cli => 'employee eid $EID full',
validations => {
eid => 'Int',
},
description => 'Full employee profile',
documentation => <<'EOH',
=pod
This resource enables any active employee to retrieve her own
full employee profile. Admins and supervisors can retrieve the
profiles of other employees.
EOH
},
# /employee/eid/:eid/minimal
'employee/eid/:eid/minimal' =>
{
parent => 'employee/eid/:eid',
handler => {
GET => 'handler_get_employee_minimal',
},
acl_profile => 'passerby',
cli => 'employee eid $EID minimal',
validations => {
eid => 'Int',
},
description => 'List minimal info on an employee',
documentation => <<'EOH',
=pod
This resource enables any employee to get minimal information
on any other employee. Useful for EID to nick conversion or to
look up another employee's email address or name.
EOH
},
# /employee/eid/:eid/team
'employee/eid/:eid/team' =>
{
parent => 'employee/eid/:eid',
handler => {
lib/App/Dochazka/REST/ResourceDefs.pm view on Meta::CPAN
cli => 'employee eid $EID team',
validations => {
eid => 'Int',
},
description => 'List the nicks of an employee\'s team members',
documentation => <<'EOH',
=pod
This resource enables administrators to list the nicks of team members
of an arbitrary employee - i.e. that employee\'s direct reports.
EOH
},
# /employee/list/?:priv
'employee/list/?:priv' =>
{
parent => 'employee',
handler => {
GET => 'handler_get_employee_list',
},
acl_profile => 'admin',
cli => 'employee list [$PRIV]',
validations => {
'priv' => $priv_validation,
},
description => 'List nicks of employees',
documentation => <<'EOH',
=pod
This resource enables the administrator to easily list the nicks of
employees. If priv is not given, all employees are listed.
EOH
},
# /employee/nick
'employee/nick' =>
{
parent => 'employee',
handler => {
POST => 'handler_post_employee_nick',
},
acl_profile => 'inactive',
cli => 'employee nick $JSON',
description => 'Insert new/update existing employee (JSON request body with nick required)',
documentation => <<'EOH',
=pod
This resource provides a way to insert/update employee objects using the
POST method, provided the employee's nick is provided in the content body.
Consider, for example, the following request body:
{ "nick" : "foobar", "fullname" : "Foo Bariful" }
If an employee "foobar" exists, such a request would change the 'fullname'
property of that employee to "Foo Bariful". On the other hand, if the employee
doesn't exist this HTTP request would cause a new employee 'foobar' to be
created.
ACL note: 'inactive' and 'active' employees can use this resource to modify
their own employee profile. Exactly which fields can be updated may differ from
site to site (see the DOCHAZKA_PROFILE_EDITABLE_FIELDS site parameter).
EOH
},
# /employee/nick/:nick
'employee/nick/:nick' =>
{
parent => 'employee',
handler => {
GET => 'handler_get_employee_nick',
PUT => 'handler_put_employee_nick',
DELETE => 'handler_delete_employee_nick',
},
acl_profile => {
GET => 'passerby',
PUT => 'inactive',
DELETE => 'admin',
},
cli => 'employee nick $NICK [$JSON]',
validations => {
'nick' => $term_validation,
},
description => "Retrieves (GET), updates/inserts (PUT), and/or deletes (DELETE) the employee specified by the ':nick' parameter",
documentation => <<'EOH',
=pod
Retrieves (GET), updates/inserts (PUT), and/or deletes (DELETE) the employee
specified by the ':nick' parameter.
=over
=item * GET
Retrieves employee object(s) by exact match. For example:
GET employee/nick/foobar
would look for an employee whose nick is 'foobar'.
=item * PUT
Inserts a new employee or updates an existing one (exact match only).
If a 'nick' property is provided in the content body and its value is
different from the nick provided in the URI, the employee's nick will be
changed to the value provided in the content body.
ACL note: 'inactive' and 'active' employees can use this resource to modify
their own employee profile. Exactly which fields can be updated may differ from
site to site (see the DOCHAZKA_PROFILE_EDITABLE_FIELDS site parameter).
=item * DELETE
Deletes an employee (exact match only). This will work only if the
exact nick exists and nothing else in the database refers to the employee
in question.
=back
EOH
},
# /employee/nick/:nick/ldap
'employee/nick/:nick/ldap' =>
{
parent => 'employee/nick/:nick',
handler => {
GET => 'handler_get_employee_ldap',
PUT => 'handler_put_employee_ldap',
},
acl_profile => {
GET => 'passerby',
PUT => 'active',
},
cli => 'employee nick $nick ldap',
validations => {
nick => $term_validation,
},
description => 'List LDAP info on an employee',
documentation => <<'EOH',
=pod
LDAP search and sync resource
=over
=item * GET
Enables any employee to perform an LDAP lookup on any other employee.
=item * PUT
Enables active employees to sync their own employee profile fields[1] from the
site's LDAP database.
Enables admin employees to sync/create[1] any existing employee from the LDAP
database. If the employee does not exist, it will be created (just the employee
object itself, without any privhistory records).
=back
[1] Which fields get synced depends on DOCHAZKA_LDAP_MAPPING site config
parameter.
EOH
},
# /employee/nick/:nick/full
'employee/nick/:nick/full' =>
{
lib/App/Dochazka/REST/ResourceDefs.pm view on Meta::CPAN
},
documentation => <<'EOH',
=pod
Retrieves an employee object by the secondary ID (must be an exact match)
EOH
},
# /employee/sec_id/:sec_id/minimal
'employee/sec_id/:sec_id/minimal' =>
{
parent => 'employee/sec_id/:sec_id',
handler => {
GET => 'handler_get_employee_minimal',
},
acl_profile => 'passerby',
cli => 'employee sec_id $sec_id minimal',
validations => {
'sec_id' => $term_validation,
},
description => 'List minimal info on an employee',
documentation => <<'EOH',
=pod
This resource enables any employee to get minimal information
on any other employee. Useful for sec_id to EID conversion or to
look up another employee's email address or name.
EOH
},
# /employee/self
'employee/self' =>
{
parent => 'employee',
handler => {
GET => 'handler_whoami',
POST => 'handler_post_employee_self',
},
acl_profile => {
'GET' => 'passerby',
'POST' => 'inactive',
},
cli => 'employee current',
description => 'Retrieve (GET) and edit (POST) our own employee profile',
documentation => <<'EOH',
=pod
With this resource, we can retrieve (GET) and/or edit (POST) our own employee
profile.
=over
=item * GET
Displays the profile of the currently logged-in employee. The information
is limited to just the employee object itself.
=item * POST
Provides a way for an employee to update certain fields of her own employee
profile. Exactly which fields can be updated may differ from site to site
(see the DOCHAZKA_PROFILE_EDITABLE_FIELDS site parameter).
=back
EOH
},
# /employee/self/full
'employee/self/full' =>
{
parent => 'employee/self',
handler => {
GET => 'handler_get_employee_self_full',
},
acl_profile => 'passerby',
cli => 'employee current priv',
description => 'Retrieve our own employee profile, privlevel, and schedule',
documentation => <<'EOH',
=pod
Displays the "full profile" of the currently logged-in employee. The
information includes the full employee object (taken from the 'current_emp'
property) as well as the employee's current privlevel and schedule, which are
looked up from the database.
N.B. The value of the "schedule" property is just the SID, not the actual
schedule record.
EOH
},
# /employee/team
'employee/team' =>
{
parent => 'employee',
handler => {
GET => 'handler_get_employee_team',
},
acl_profile => 'active',
cli => 'team',
description => 'List nicks of the logged-in employee\'s team members',
documentation => <<'EOH',
=pod
This resource enables supervisors to easily list the nicks of
employees in their team - i.e. their direct reports.
EOH
},
};
=head2 Genreport resources
=cut
$defs->{'genreport'} = {
# /genreport
'genreport' =>
{
parent => '/',
lib/App/Dochazka/REST/ResourceDefs.pm view on Meta::CPAN
=pod
This resource presents a list of subresources, all related to privilege histories.
EOH
},
'schedule/history' =>
{
parent => 'schedule',
handler => 'handler_noop',
cli => 'schedule history',
description => 'Schedule history resources',
documentation => <<'EOH',
=pod
This resource presents a list of subresources, all related to schedule histories.
EOH
},
'priv/history/eid/:eid' =>
{
parent => 'priv/history',
handler => {
GET => 'handler_history_get_multiple',
POST => 'handler_history_post',
},
acl_profile => {
GET => 'inactive',
POST => 'admin',
},
cli => 'priv history eid $EID [$JSON]',
validations => {
'eid' => 'Int',
},
description => 'Retrieves entire history of privilege level changes for employee with the given EID (GET); or, with an appropriate content body, adds (POST) a record to employee\'s privhistory',
documentation => <<'EOH',
=pod
Retrieves entire history of privilege level changes for employee with the given
EID (GET); or, with an appropriate content body, adds (POST) a record to
employee\'s privhistory.
=over
=item * GET
Retrieves the "privhistory", or history of changes in
privilege level, of the employee with the given EID.
=item * POST
Adds a record to the privhistory of the given employee. The content body should
contain two properties: "effective" (a timestamp) and "priv" (one of
"passerby", "inactive", "active", or "admin").
It is assumed that schedule histories will be built up record-by-record;
insertion of multiple history records in a single request is not supported.
=back
Update note: histories can be updated by adding new records and deleting old
ones. Existing history records cannot be changed. Adds/deletes should be
performed with due care - especially with regard to existing employee
attendance data (if any).
EOH
},
'schedule/history/eid/:eid' =>
{
parent => 'schedule/history',
handler => {
GET => 'handler_history_get_multiple',
POST => 'handler_history_post',
},
acl_profile => {
GET => 'inactive',
POST => 'admin',
},
cli => 'schedule history eid $EID [$JSON]',
validations => {
'eid' => 'Int',
},
description => 'Retrieves entire history of schedule changes for employee with the given EID (GET); or, with an appropriate content body, adds (POST) a record to employee\'s schedule history',
documentation => <<'EOH',
=pod
Retrieves entire history of schedule changes for employee with the given EID
(GET); or, with an appropriate content body, adds (POST) a record to
employee\'s schedule history.
=over
=item * GET
Retrieves the full history of schedule changes of the employee with the given EID.
For partial history, see 'schedule/history/eid/:eid/:tsrange'.
=item * POST
Adds a record to the schedule history of the given employee. The content body should
contain two properties: "effective" (a timestamp) and "sid" (the ID of the schedule).
Alternatively, an "scode" property (schedule code) can be sent instead of "sid".
It is assumed that schedule histories will be built up record-by-record;
insertion of multiple history records in a single request is not supported.
=back
Update note: histories can be updated by adding new records and deleting old
ones. Existing history records cannot be changed. Adds/deletes should be
performed with due care - especially with regard to existing employee
attendance data (if any).
EOH
},
'priv/history/eid/:eid/:tsrange' =>
{
parent => 'priv/history',
handler => {
GET => 'handler_history_get_multiple',
},
acl_profile => 'inactive',
cli => 'priv history eid $EID $TSRANGE',
description => 'Get a slice of history of privilege level changes for employee with the given EID',
validations => {
'eid' => 'Int',
'tsrange' => $tsrange_validation,
},
documentation => <<'EOH',
=pod
Retrieves a slice (given by the tsrange argument) of the employee's
"privhistory" (history of changes in privilege level).
EOH
},
'schedule/history/eid/:eid/:tsrange' =>
{
parent => 'schedule/history',
handler => {
GET => 'handler_history_get_multiple',
},
acl_profile => 'inactive',
cli => 'schedule history eid $EID $TSRANGE',
description => 'Get a slice of history of schedule changes for employee with the given EID',
validations => {
'eid' => 'Int',
'tsrange' => $tsrange_validation,
},
documentation => <<'EOH',
=pod
Retrieves a slice (given by the tsrange argument) of the employee's
"schedule history" (history of changes in schedule).
EOH
},
'priv/history/eid/:eid/:ts' =>
{
parent => 'priv/history',
handler => {
GET => 'handler_history_get_single',
},
acl_profile => 'inactive',
cli => 'priv history eid $EID $TS',
description => 'Get the privhistory record effective at a given timestamp',
validations => {
'eid' => 'Int',
'ts' => $ts_validation,
lib/App/Dochazka/REST/ResourceDefs.pm view on Meta::CPAN
{
parent => 'schedule/history',
handler => {
GET => 'handler_history_get_single',
},
acl_profile => 'inactive',
cli => 'schedule history eid $EID now',
description => 'Get the privhistory record effective as of "now" (the current timestamp)',
validations => {
'eid' => 'Int',
},
documentation => <<'EOH',
=pod
Retrieves an employee's effective schedhistory record (status change) as of
"now" (the current timestamp).
EOH
},
'priv/history/nick/:nick' =>
{
parent => 'priv/history',
handler => {
GET => 'handler_history_get_multiple',
POST => 'handler_history_post',
},
acl_profile => {
GET => 'inactive',
POST => 'admin',
},
cli => 'priv history nick $NICK [$JSON]',
validations => {
'nick' => $term_validation,
},
description => 'Retrieves entire history of privilege level changes for employee with the given nick (GET); or, with an appropriate content body, adds (PUT) a record to employee\'s privhistory',
documentation => <<'EOH',
=pod
Retrieves entire history of privilege level changes for employee with the given
nick (GET); or, with an appropriate content body, adds (PUT) a record to
employee\'s privhistory.
=over
=item * GET
Retrieves the "privhistory", or history of changes in
privilege level, of the employee with the given nick.
=item * POST
Adds a record to the privhistory of the given employee. The content body should
contain two properties: "effective" (a timestamp) and "priv" (one of
"passerby", "inactive", "active", or "admin").
It is assumed that schedule histories will be built up record-by-record;
insertion of multiple history records in a single request is not supported.
=back
Update note: histories can be updated by adding new records and deleting old
ones. Existing history records cannot be changed. Adds/deletes should be
performed with due care - especially with regard to existing employee
attendance data (if any).
EOH
},
'schedule/history/nick/:nick' =>
{
parent => 'schedule/history',
handler => {
GET => 'handler_history_get_multiple',
POST => 'handler_history_post',
},
acl_profile => {
GET => 'inactive',
POST => 'admin',
},
cli => 'schedule history nick $NICK [$JSON]',
validations => {
'nick' => $term_validation,
},
description => 'Retrieves entire history of schedule changes for employee with the given nick (GET); or, with an appropriate content body, adds (PUT) a record to employee\'s schedule history',
documentation => <<'EOH',
=pod
Retrieves entire history of schedule changes for employee with the given nick
(GET); or, with an appropriate content body, adds (PUT) a record to employee\'s
schedule history.
=over
=item * GET
Retrieves the full history of schedule changes of the employee with the given nick.
For partial histories, see 'schedule/history/nick/:nick/:tsrange'.
=item * POST
Adds a record to the schedule history of the given employee. The content body should
contain two properties: "effective" (a timestamp) and "sid" (the ID of the schedule).
Alternatively, an "scode" property (schedule code) can be sent instead of "sid".
It is assumed that schedule histories will be built up record-by-record;
insertion of multiple history records in a single request is not supported.
=back
Update note: histories can be updated by adding new records and deleting old
ones. Existing history records cannot be changed. Adds/deletes should be
performed with due care - especially with regard to existing employee
attendance data (if any).
EOH
},
'priv/history/nick/:nick/:tsrange' =>
{
parent => 'priv/history',
handler => {
GET => 'handler_history_get_multiple',
},
acl_profile => 'inactive',
cli => 'priv history nick $NICK $TSRANGE',
validations => {
'nick' => $term_validation,
'tsrange' => $tsrange_validation,
},
description => 'Get partial history of privilege level changes for employee with the given nick ' .
'(i.e, limit to given tsrange)',
documentation => <<'EOH',
=pod
Retrieves a slice (given by the tsrange argument) of the employee's
"privhistory" (history of changes in privilege level).
EOH
},
'schedule/history/nick/:nick/:tsrange' =>
{
parent => 'schedule/history',
handler => {
GET => 'handler_history_get_multiple',
},
acl_profile => 'inactive',
cli => 'schedule history nick $NICK $TSRANGE',
validations => {
'nick' => $term_validation,
'tsrange' => $tsrange_validation,
},
description => 'Get partial history of schedule changes for employee with the given nick ' .
'(i.e, limit to given tsrange)',
documentation => <<'EOH',
=pod
Retrieves a slice (given by the tsrange argument) of the employee's
"schedule history" (history of changes in schedule).
EOH
},
'priv/history/phid/:phid' =>
{
parent => 'priv/history',
handler => {
GET => 'handler_history_get_phid',
POST => 'handler_history_post_phid',
DELETE => 'handler_history_delete_phid',
},
acl_profile => 'admin',
cli => 'priv history phid $PHID',
lib/App/Dochazka/REST/ResourceDefs.pm view on Meta::CPAN
EOH
},
# /interval/fillup
'interval/fillup' =>
{
parent => 'interval',
handler => {
POST => 'handler_interval_fillup',
},
acl_profile => {
POST => 'active',
},
cli => 'interval fillup',
description => 'Generate intervals according to schedule',
documentation => <<'EOH',
=pod
Used with POST to create multiple attendance intervals for an employee,
according to the prevailing schedule.
The request body is a JSON object with the following parameters:
=over
=item * C<eid> (the EID of the employee to create intervals for; alternatively, C<nick> or C<sec_id>)
=item * C<tsrange> (the time span over which to create intervals)
=item * C<datelist> (a list of dates to create intervals for)
=item * C<dry_run> (boolean value)
=item * C<aid> (the AID of the activity; alternatively, C<code>)
=item * C<desc> (optional interval description)
=item * C<remark> (optional remark)
=back
If C<tsrange> is provided, C<datelist> should be omitted - and vice versa.
If C<dry_run> is true, the resource does not change the database state.
EOH
},
# /interval/iid
'interval/iid' =>
{
parent => 'interval',
handler => {
POST => 'handler_post_interval_iid',
},
acl_profile => 'active',
cli => 'interval iid $JSON',
description => 'Update an existing interval object via POST request (iid must be included in request body)',
documentation => <<'EOH',
=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
lib/App/Dochazka/REST/ResourceDefs.pm view on Meta::CPAN
=head2 Lock resources
=cut
$defs->{'lock'} = {
# /lock
'lock' =>
{
parent => '/',
handler => 'handler_noop',
acl_profile => 'passerby',
cli => 'lock',
description => 'Parent for lock resources',
documentation => <<'EOH',
=pod
Parent for lock resources
EOH
},
# /lock/eid/:eid/:tsrange
'lock/eid/:eid/:tsrange' =>
{
parent => 'lock',
handler => {
GET => 'handler_get_lock_eid',
},
acl_profile => 'active',
cli => 'lock eid $EID $TSRANGE',
validations => {
'eid' => 'Int',
'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/lid
'lock/lid' =>
{
parent => 'lock',
handler => {
POST => 'handler_post_lock_lid',
},
acl_profile => 'admin',
cli => 'lock lid $JSON',
description => 'Update an existing lock object via POST request (lid must be included in request body)',
documentation => <<'EOH',
=pod
Enables existing lock 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 'lid' property, the value of which specifies the lid to be
updated.
EOH
},
# /lock/lid/:lid
'lock/lid/:lid' =>
{
parent => 'lock',
handler => {
GET => 'handler_get_lock_lid',
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>.
( run in 1.489 second using v1.01-cache-2.11-cpan-63c85eba8c4 )