NAME
App::Dochazka::REST::Docs::Resources - Documentation of REST resources
DESCRIPTION
This is a POD-only module containing documentation on all the REST resources defined under config/dispatch
. This module is auto-generated.
RESOURCES
Top-level
Miscellaneous resources that don't fit under any specific category.
/
Display available top-level resources for given HTTP method
HTTP methods: POST
GET
DELETE
PUT
CLI: $METHOD
ACL profile: passerby
This is the toppest of the top-level targets or, if you wish, the "root target". If the base UID of your App::Dochazka::REST instance is http://dochazka.site:5000 and your username/password are "demo/demo", then this resource is triggered by either of the URLs:
http://demo:demo@dochazka.site:5000
http://demo:demo@dochazka.site:5000/
In terms of behavior, the "" resource is identical to "help" -- it returns the set of top-level resources available to the user.
activity
Display available employee resources for given HTTP method
HTTP methods: PUT
DELETE
GET
POST
CLI: $METHOD employee
ACL profile: passerby
Lists activity resources available to the logged-in employee.
bugreport
Display the address for reporting bugs in App::Dochazka::REST
HTTP methods: GET
CLI: $METHOD bugreport
ACL profile: passerby
Returns a "report_bugs_to" key in the payload, containing the address to report bugs to.
docu
Display on-line Plain Old Documentation (POD) on the resource whose name is provided in the request body (in double-quotes)
HTTP methods: POST
CLI: $METHOD docu $RESOURCE
ACL profile: passerby
This resource provides access to App::Dochazka::REST on-line help documentation. It expects to find a resource (e.g. "employee/eid/:eid" including the double-quotes, and without leading or trailing slash) in the request body. It returns a string containing the POD source code of the resource documentation.
docu/html
Display on-line HTML documentation on the resource whose name is provided in the request body (in double-quotes)
HTTP methods: POST
CLI: $METHOD docu html $RESOURCE
ACL profile: passerby
This resource provides access to App::Dochazka::REST on-line help documentation. It expects to find a resource (e.g. "employee/eid/:eid" including the double-quotes, and without leading or trailing slash) in the request body. It returns HTML source code of the resource documentation.
echo
Echo the request body
HTTP methods: POST
CLI: $METHOD echo [$JSON]
ACL profile: admin
This resource simply takes whatever content body was sent and echoes it back in the response body.
employee
Display available employee resources for given HTTP method
HTTP methods: POST
DELETE
PUT
GET
CLI: $METHOD employee
ACL profile: passerby
Lists employee resources available to the logged-in employee.
forbidden
A resource that is forbidden to all
HTTP methods: POST
GET
DELETE
PUT
CLI: $METHOD forbidden
ACL profile: forbidden to all
This resource always returns 405 Method Not Allowed, no matter what.
help
Display available top-level resources for given HTTP method
HTTP methods: PUT
DELETE
GET
POST
CLI: $METHOD help
ACL profile: passerby
The purpose of the "help" resource is to give the user an overview of all the top-level resources available to her, with regard to her privlevel and the HTTP method being used.
If the HTTP method is GET, only resources with GET targets will be displayed (same applies to other HTTP methods)
If the user's privlevel is 'inactive', only resources whose ACL profile is 'inactive' or lower (i.e., 'inactive' or 'passerby') will be displayed
The information provided is sent as a JSON string in the HTTP response body, and includes the resource's name, full URI, ACL profile, and brief description, as well as a link to the App::Dochazka::REST on-line documentation.
metaparam/:param
Display (GET) or set (PUT) meta configuration parameter
HTTP methods: GET
DELETE
PUT
CLI: $METHOD metaparam $PARAM [$JSON]
ACL profile: admin
GET
Assuming that the argument
:param
is the name of an existing meta parameter, displays the parameter's value and metadata (type, name, file and line number where it was defined). This resource is available only to users withadmin
privileges.PUT
Regardless of whether
:param
is an existing metaparam or not, set that parameter's value to the (entire) request body. If the request body is "123", then the parameter will be set to that value. If it is { "value" : 123 }, then it will be set to that structure.DELETE
If the argument is an existing metaparam, delete that parameter (NOT IMPLEMENTED)
not_implemented
A resource that will never be implemented
HTTP methods: GET
DELETE
PUT
POST
CLI: $METHOD not_implemented
ACL profile: passerby
Regardless of anything, returns a NOTICE status with status code DISPATCH_RESOURCE_NOT_IMPLEMENTED
priv
Display available priv resources for given HTTP method
HTTP methods: DELETE
PUT
GET
POST
CLI: $METHOD priv
ACL profile: passerby
Lists priv resources available to the logged-in employee.
schedule
Display available schedule resources for given HTTP method
HTTP methods: GET
PUT
DELETE
POST
CLI: $METHOD schedule
ACL profile: passerby
Lists schedule resources available to the logged-in employee.
session
Display the current session
HTTP methods: GET
CLI: $METHOD session
ACL profile: passerby
Dumps the current session data (server-side).
siteparam/:param
Display site configuration parameter
HTTP methods: GET
CLI: $METHOD siteparam $PARAM
ACL profile: admin
Assuming that the argument ":param" is the name of an existing site parameter, displays the parameter's value and metadata (type, name, file and line number where it was defined).
version
Display App::Dochazka::REST version
HTTP methods: GET
CLI: $METHOD version
ACL profile: passerby
Shows the App::Dochazka::REST version running on the present instance.
whoami
Display the current employee (i.e. the one we authenticated with)
HTTP methods: GET
CLI: $METHOD whoami
ACL profile: passerby
Displays the profile of the currently logged-in employee (same as "employee/current")
Activity
Resources related to activities.
activity/aid
Update an existing activity object via POST request (AID must be included in request body)
HTTP methods: POST
CLI: $METHOD activity aid
ACL profile: admin
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.
activity/aid/:aid
GET, PUT, or DELETE an activity object by its AID
HTTP methods: PUT
DELETE
GET
CLI: $METHOD activity aid $AID
ACL profile: DELETE: admin, PUT: admin, GET: active,
GET
Retrieves an activity object by its AID.
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" }
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.
activity/all
Retrieve all activity objects (excluding disabled ones)
HTTP methods: GET
CLI: $METHOD activity all
ACL profile: active
Retrieves all activity objects in the database (excluding disabled activities).
activity/all/disabled
Retrieve all activity objects, including disabled ones
HTTP methods: GET
CLI: $METHOD activity all disabled
ACL profile: admin
Retrieves all activity objects in the database (including disabled activities).
activity/code
Update an existing activity object via POST request (activity code must be included in request body)
HTTP methods: POST
CLI: $METHOD activity aid
ACL profile: admin
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.
activity/code/:code
GET, PUT, or DELETE an activity object by its code
HTTP methods: GET
PUT
DELETE
CLI: $METHOD activity code $CODE
ACL profile: GET: active, PUT: admin, DELETE: admin,
GET
Retrieves an activity object by its code.
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" }
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.
activity/help
Display available activity resources for given HTTP method
HTTP methods: GET
DELETE
PUT
POST
CLI: $METHOD activity help
ACL profile: passerby
Displays information on all activity resources available to the logged-in employee, according to her privlevel.
Employee
Resources related to employee profiles.
employee/count
Display total count of employees (all privilege levels)
HTTP methods: GET
CLI: $METHOD employee count
ACL profile: admin
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. Keep this in mind when evaluating the number returned.
employee/count/:priv
Display total count of employees with given privilege level
HTTP methods: GET
CLI: $METHOD employee count $PRIV
ACL profile: admin
Gets the number of employees with a given privilege level. Valid privlevels are:
passerby
inactive
active
admin
employee/current
Display the current employee (i.e. the one we authenticated with)
HTTP methods: GET
CLI: $METHOD employee current
ACL profile: passerby
Displays the profile of the currently logged-in employee. The information is limited to just the employee object itself.
employee/current/priv
Display the privilege level of the current employee (i.e. the one we authenticated with)
HTTP methods: GET
CLI: $METHOD employee current priv
ACL profile: passerby
Displays the "full profile" of the currently logged-in employee. The information includes the employee object in the 'current_emp' property and the employee's privlevel in the 'priv' property.
employee/eid
Update existing employee (JSON request body with EID required)
HTTP methods: POST
CLI: $METHOD employee eid $JSON
ACL profile: admin
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).
employee/eid/:eid
GET: look up employee (exact match); PUT: update existing employee; DELETE: delete employee
HTTP methods: GET
DELETE
PUT
CLI: $METHOD employee eid $EID [$JSON]
ACL profile: admin
GET
Retrieves an employee object by its EID.
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 reques would changesthe 'fullname' property of the employee with EID 43 to "Foo Bariful" (provided such an employee exists). Any 'eid' property provided in the content body will be ignored.
DELETE
Deletes the employee with the given EID (will only work if the EID exists and nothing in the database refers to it).
employee/help
Display available employee resources for given HTTP method
HTTP methods: POST
GET
DELETE
PUT
CLI: $METHOD employee help
ACL profile: passerby
Displays information on all employee resources available to the logged-in employee, according to her privlevel.
employee/nick
Insert new/update existing employee (JSON request body with nick required)
HTTP methods: POST
CLI: $METHOD employee nick $JSON
ACL profile: admin
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.
employee/nick/:nick
Retrieves (GET), updates/inserts (PUT), and/or deletes (DELETE) the employee specified by the ':nick' parameter
HTTP methods: GET
DELETE
PUT
CLI: $METHOD employee nick $NICK [$JSON]
ACL profile: admin
GET
Retrieves employee object(s) by exact match or % wildcard. For example:
GET employee/nick/foobar
would look for an employee whose nick is 'foobar'. Another example:
GET employee/nick/foo%
would return a list of employees whose nick starts with 'foo'.
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.
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.
Privilege
Resources related to employee privileges and privhistories.
priv/eid/:eid/?:ts
Get the present privlevel of arbitrary employee, or with optional timestamp, that employee's privlevel as of that timestamp
HTTP methods: GET
CLI: $METHOD priv eid $EID [$TIMESTAMP]
ACL profile: admin
This resource retrieves the privlevel of an arbitrary employee specified by EID.
If no timestamp is given, the present privlevel is retrieved. If a timestamp is present, the privlevel as of that timestamp is retrieved.
priv/help
Display priv resources
HTTP methods: POST
GET
DELETE
PUT
CLI: $METHOD priv help
ACL profile: passerby
This resource retrieves a listing of all resources available to the caller (currently logged-in employee).
priv/history/eid/:eid
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
HTTP methods: GET
POST
CLI: $METHOD priv history eid $EID [$JSON]
ACL profile: admin
GET
Retrieves the "privhistory", or history of changes in privilege level, of the employee with the given EID.
POST
Adds a record to the privhistory of the given employee. The content body should contain two properties: "timestamp" and "privlevel".
It is assumed that privhistories will be built up record-by-record, but this dispatch target could conceivably support insertion of multiple privhistory records.
priv/history/eid/:eid/:tsrange
Get a slice of history of privilege level changes for employee with the given EID
HTTP methods: GET
CLI: $METHOD priv history eid $EID $TSRANGE
ACL profile: admin
Retrieves a slice (given by the tsrange argument) of the employee's "privhistory" (history of changes in privilege level).
priv/history/nick/:nick
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
HTTP methods: POST
GET
CLI: $METHOD priv history nick $NICK [$JSON]
ACL profile: admin
GET
Retrieves the "privhistory", or history of changes in privilege level, of the employee with the given nick.
POST
Adds a record to the privhistory of the given employee. The content body should contain two properties: "timestamp" and "privlevel".
It is assumed that privhistories will be built up record-by-record, but this dispatch target could conceivably support insertion of multiple privhistory records.
priv/history/nick/:nick/:tsrange
Get partial history of privilege level changes for employee with the given nick (i.e, limit to given tsrange)
HTTP methods: GET
CLI: $METHOD priv history nick $NICK $TSRANGE
ACL profile: admin
Retrieves a slice (given by the tsrange argument) of the employee's "privhistory" (history of changes in privilege level).
priv/history/phid/:phid
Retrieves (GET) or deletes (DELETE) a single privilege history record by its PHID
HTTP methods: DELETE
GET
CLI: $METHOD priv history phid $PHID
ACL profile: admin
GET
Retrieves a privhistory record by its PHID.
DELETE
Deletes a privhistory record by its PHID.
(N.B.: to add a privhistory record, use "PUT priv/history/eid/:eid" or "PUT priv/history/nick/:nick")
priv/history/self/?:tsrange
Retrieves privhistory of present employee, with option to limit to :tsrange
HTTP methods: GET
CLI: $METHOD priv history self [$TSRANGE]
ACL profile: active
This resource retrieves the "privhistory", or history of changes in privilege level, of the present employee. Optionally, the listing can be limited to a specific tsrange such as "[2014-01-01, 2014-12-31)".
priv/nick/:nick/?:ts
Get the present privlevel of arbitrary employee, or with optional timestamp, that employee's privlevel as of that timestamp
HTTP methods: GET
CLI: $METHOD priv nick $NICK [$TIMESTAMP]
ACL profile: admin
This resource retrieves the privlevel of an arbitrary employee specified by nick.
If no timestamp is given, the present privlevel is retrieved. If a timestamp is present, the privlevel as of that timestamp is retrieved.
priv/self/?:ts
Get the present privlevel of the currently logged-in employee, or with optional timestamp, that employee's privlevel as of that timestamp
HTTP methods: GET
CLI: $METHOD priv self [$TIMESTAMP]
ACL profile: passerby
This resource retrieves the privlevel of the caller (currently logged-in employee).
If no timestamp is given, the present privlevel is retrieved. If a timestamp is present, the privlevel as of that timestamp is retrieved.
Schedule
Resources related to employee schedules and schedhistories.
schedule/all
Retrieves (GET) all non-disabled schedules
HTTP methods: GET
CLI: $METHOD schedule all
ACL profile: admin
This resource returns a list (array) of all schedules for which the 'disabled' field has either not been set or has been set to 'false'.
schedule/all/disabled
Retrieves (GET) all schedules (disabled and non-disabled)
HTTP methods: GET
CLI: $METHOD schedule all disabled
ACL profile: admin
This resource returns a list (array) of all schedules, regardless of the contents of the 'disabled' field.
schedule/eid/:eid/?:ts
Get the current schedule of arbitrary employee, or with optional timestamp, that employee's schedule as of that timestamp
HTTP methods: GET
CLI: $METHOD schedule eid $EID [$TIMESTAMP]
ACL profile: admin
This resource retrieves the schedule of an arbitrary employee specified by EID.
If no timestamp is given, the current schedule is retrieved. If a timestamp is present, the schedule as of that timestamp is retrieved.
schedule/help
Display schedule resources
HTTP methods: POST
GET
DELETE
PUT
CLI: $METHOD schedule help
ACL profile: passerby
This resource retrieves a listing of all schedule resources available to the caller (currently logged-in employee).
schedule/history/eid/:eid
Retrieves (GET) entire history of schedule changes for employee with the given EID; adds (POST) a record to schedule history of employee
HTTP methods: POST
GET
CLI: $METHOD schedule history eid $EID [$JSON]
ACL profile: admin
GET
Retrieves the "schedule history", or history of changes in schedule, of the employee with the given EID.
POST
Adds a record to the schedule history of the given employee. The content body should contain two properties: "effective" (timestamp) and "sid" (integer).
schedule/history/eid/:eid/:tsrange
Retrieves a slice of history of schedule changes for employee with the given EID
HTTP methods: GET
CLI: $METHOD schedule history eid $EID $TSRANGE
ACL profile: admin
Retrieves a slice (given by the tsrange argument) of the employee's "schedule history" (history of changes in schedule).
schedule/history/nick/:nick
Retrieves (GET) entire history of schedule changes for employee with the given nick; adds (POST) a record to schedule history of employee
HTTP methods: POST
GET
CLI: $METHOD schedule history nick $NICK [$JSON]
ACL profile: admin
GET
Retrieves the "schedule history", or history of changes in schedule, of the employee with the given nick.
POST
Adds a record to the schedule history of the given employee. The content body should contain two properties: "effective" (timestamp) and "sid" (integer).
schedule/history/nick/:nick/:tsrange
Get partial history of schedule changes for employee with the given nick (i.e, limit to given tsrange)
HTTP methods: GET
CLI: $METHOD schedule history nick $NICK $TSRANGE
ACL profile: admin
Retrieves a slice (given by the tsrange argument) of the employee's "schedule history" (history of changes in schedule).
schedule/history/self/?:tsrange
Get schedule history of current employee, with option to limit to :tsrange
HTTP methods: GET
CLI: $METHOD schedule history current [$TSRANGE]
ACL profile: active
This resource retrieves the "schedule history", or history of changes in schedule, of the current employee. Optionally, the listing can be limited to a specific tsrange such as "[2014-01-01, 2014-12-31)".
schedule/history/shid/:shid
GET or DELETE a schedule record by its SHID
HTTP methods: DELETE
GET
CLI: $METHOD schedule history shid $SHID
ACL profile: admin
GET
Retrieves a schedule history record by its SHID.
DELETE
Deletes a schedule history record by its SHID.
(N.B.: to add a schedule history record, use "PUT schedule/history/eid/:eid" or "PUT schedule/history/nick/:nick")
schedule/intervals
Insert schedules
HTTP methods: POST
CLI: $METHOD schedule intervals
ACL profile: admin
Given a set of intervals, all of which must fall within a single contiguous 168-hour (7-day) period, this resource performs all actions necessary to either create a new schedule from those intervals or verify that an equivalent schedule already exists.
Sample JSON:
[
"[2014-09-22 08:00, 2014-09-22 12:00)",
"[2014-09-22 12:30, 2014-09-22 16:30)",
"[2014-09-23 08:00, 2014-09-23 12:00)",
"[2014-09-23 12:30, 2014-09-23 16:30)",
"[2014-09-24 08:00, 2014-09-24 12:00)",
"[2014-09-24 12:30, 2014-09-24 16:30)",
"[2014-09-25 08:00, 2014-09-25 12:00)",
"[2014-09-25 12:30, 2014-09-25 16:30)"
]
Read on for details:
First, a set of scratch intervals is created in the 'schedintvls' table. If this succeeds, an INSERT operation is used to create a new record in the 'schedule' table. This operation has two possible successful outcomes depending on whether such a schedule already existed in the database, or not. The status codes for these outcomes are DISPATCH_SCHEDULE_OK and DISPATCH_SCHEDULE_INSERT_OK, respectively.
In both cases, the underlying scratch intervals are deleted automatically. (All operations on the 'schedintlvs' table are supposed to be hidden from Dochazka clients.)
Note that many sets of intervals can map to a single schedule (the conversion process is only interested in the day of the week), so this resource may return DISPATCH_SCHEDULE_OK more often than you think.
Whether or not the exact schedule existed already, if the underlying database operation is successful the payload will contain three properties: 'sid' (the SID assigned to the schedule containing the intervals), 'intervals' (the intervals themselves), and 'schedule' (the intervals as they appear after being converted into the format suitable for insertion into the 'schedule' table).
N.B. At present there is no way to just check for the existence of a schedule corresponding to a given set of intervals.
schedule/nick/:nick/?:ts
Get the current schedule of arbitrary employee, or with optional timestamp, that employee's schedule as of that timestamp
HTTP methods: GET
CLI: $METHOD schedule nick $NICK [$TIMESTAMP]
ACL profile: admin
This resource retrieves the schedule of an arbitrary employee specified by nick.
If no timestamp is given, the current schedule is retrieved. If a timestamp is present, the schedule as of that timestamp is retrieved.
schedule/self/?:ts
Get the current schedule of the currently logged-in employee, or with optional timestamp, that employee's schedule as of that timestamp
HTTP methods: GET
CLI: $METHOD schedule current [$TIMESTAMP]
ACL profile: passerby
This resource retrieves the schedule of the caller (currently logged-in employee).
If no timestamp is given, the current schedule is retrieved. If a timestamp is present, the schedule as of that timestamp is retrieved.
schedule/sid/:sid
Retrieves, updates, or deletes a schedule by its SID
HTTP methods: POST
GET
DELETE
CLI: $METHOD schedule sid $SID
ACL profile: admin
GET
An integer SID must be given as an URI parameter. If a schedule with this SID is found, it is returned in the payload.
POST
This resource/method provides a way to set (modify) the 'remark' and 'disabled' fields of a schedule record. Simply provide the properties and their new values in the request body, e.g.:
{ "remark" : "foobar", "disabled" : "t" }
DELETE
An integer SID must be given as an URI parameter. If found, the schedule with that SID will be deleted in an atomic operation. If the operation is sucessful the return status will be "OK".
AUTHOR
Nathan Cutler ncutler@suse.cz