|
Overview
The CirrusPrint server provides REST API access for use by external programs or custom forms within CirrusPrint. The interface has predefined end points as well as customizable ones. API access is controlled based on site users and browser-type users defined in Locations/Users.
| • | Site users that have been configured as API Users can access the API for any company they are assigned rights to. If a user is both an Admin user and an API user, then they can access the API for any company. For other users, a company must be supplied in the login. To specify a company, you can either use a GET or POST field "company" or "companyid" to set the value, or use the syntax "companyid\userid".
|
| • | Location users are granted read-only API access to their respective companies, plus job submission access. A location user uses a login with the user ID of userid@companyid and the location password. |
To access the API, use a specific URL path. The internal web server, if it is running with default ports, would be accessed as:
http://server:8482/run/api/endpoint
https://server:8483/run/api/endpoint
An external Apache server is accessed via the configured name space defined in the system configuration:
https://server/namespace/run/api/endpoint
Authentication and Sessions
To login, the API request can contain two fields, s_userid and s_password, to supply a login and password. These are validated each time they are supplied, and stored with a session record.
A browser-based session will normally maintain the session ID with a cookie, enabling one session record to be used as long the session is active, typically 12 hours. When using the API programmatically, cookie management is not automatic, so an alternative means to create and re-use a session is available:
| • | Store the value returned by the getsesid endpoint, which will be a 20-character sessionID value. Supply this endpoint with s_userid and s_password fields (i.e. /run/api/getsesid?s_userid=userID&s_password=password).
|
| • | For any other endpoint, include a field "sesid=sessionID" in the GET or POST data. As long as the session remains active, the user and password associated with that session will be used. |
Endpoints
The predefined endpoints are defined in the file prog/api.ini. Each section of this ini file names an end point, and the code associated with that API function is in the body of that section. This code is written in PxPlus, a dialect of the Basic language.
Custom endpoints can be defined in two additional files, which are not included with CirrusPrint and therefore are not overwritten by updates to CirrusPrint. The files are "data/api.ini" for site-wide definitions, and data/company/api.ini for company-specific definitions. The interface looks for endpoint definitions first in the standard prog/api.ini file, and if not found, it then looks in the site ini file, and finally the company ini file.
Several endpoints return structured data, the format of which can be specified. Those formats are: xml, json, and prop (which is plain text in "properties" format, which is name=value pairs in linefeed-separated lines; use \n mnemonic sequences for linefeeds in values). The format is specified with a GET or POST field format=format. Some endpoints returns lists, where the default format is tab-separated-values (tsv). This format includes a header line.
Errors are returned as plain text, even if a different format is specified. These are prefixed with "API Error: ". Therefore, always verify the format of the returned data, particularly if you are expecting xml or json format.
Unless otherwise noted, you can use either GET or POST methods in transactions, where POST transactions have the content type "application/x-www-form-urlencoded", or "multipart/form-data" if a file upload is to be included. Note also there is a "putfile" endpoint that uses the PUT method if you simply want to upload a file ahead of some other action. Many endpoints require a company ID. If a login includes a company ID, such as a "location@company", that company code is used. Otherwise, the company can be set with either "companyid=companyid" or "company=companyid".
Predefined Endpoints
delcomp
|
Deletes the specified company. Only admin users are allowed to run this endpoint.
companyid=companyid
|
deldev
|
Deletes the specified device records. Only site users can run this endpoint.
companyid=company
locid=locationID
devid=deviceID
|
delloc
|
Deletes the specified location record. Only site users can run this endoint.
companyid=company
locid=locationID
|
fileinfo
|
Returns either a plain text error message prefixed with "Error opening ", or a JSON object with "type" and "size" fields, where type reports the system-determined MIME type.
file=filename
|
getcomp
|
Returns properties of the specified company, in the format specified by the format field. If the company is invalid, empty fields are returned.
companyid=company
format=prop|xml|json (default=prop)
Note non-admin users may only retrieve information about the company associated with their login.
|
getdev
|
Returns properties of the specified device record. If the device is invalid, empty fields are returned.
companyid=company
locid=locationID
devid=deviceID
format=prop|xml|json (default=prop)
|
getdevices
|
Returns a list of all fields for all devices for the company, or for a specific location. The default format is tab-separated values.
format=tsv|xml|json
locid=locationID (optional; if supplied, only this location's devices are returned)
|
getlocations
|
Returns a list of all fields for all locations in the company. The default format is tab-separated values.
format=tsv|xml|json
|
getloc
|
Returns properties of the specified location record. If the location is invalid, empty fields are returned.
companyid=company
locid=locationID
format=prop|xml|json (default=prop)
|
getsources
|
Returns a list of all fields for all sources in the company. The default format is tab-separated values.
format=tsv|xml|json
|
getsrc
|
Returns properties of the specified source record. If the source ID is invalid, empty fields are returned.
companyid=company
srcid=sourceID
format=prop|xml|json (default=prop)
|
jobstatus
|
Returns a list of job status records in JSON format, as an array of objects. The jobs to be returned are specified as a comma-separted list. There can be multiple objects per job, as jobs can be sent to multiple devices.
joblist=list (comma-separated job ID's)
|
jsscript
|
Returns a file, with a Content-Type header of "text/javascript". Useful if your custom forms require a javascript file loaded from the web/forms directory.
|
putcomp
|
Updates the company record for the specified company. Note that only admin users can update company records. The companyid is required. Missing fields retain existing values or are set to default values.
| • | notes=value (use \n for linefeeds) |
| • | vhostname=URL-prefixes to match to this company, separated by \n |
| • | printports=startport-endport (used for automatic port allocation on new sources) |
| • | maxinputs=integer (used to control how many sources are monitored by a single process) |
|
putdev
|
Updates the device record for the specified location/device. Only site users can update records. Missing fields retain existing values or are set to default values.
| • | targettype=0|1|2|3|4 (0=printer, 1=file, 2=command, 3=open/view, 4=network printer) |
| • | preferredformat=pdf|pcl5|pcl6|pcl6c|ps|psc (zero or more semi-colon delimited values - used for implicit format conversions) |
| • | defpaper=letter|legal|a3|a4|a5 (used when converting images to preferred format) |
|
putfile
|
This endpoint requires a PUT method, and the posted data is stored in a temporary file. The name of the file is returned as plain text. The file will reside on the server for a few hours, so this is intended to enable pushing files to the server for immediate use by additional API functions. An example is in the web/forms/sendto.html file.
|
putloc
|
Updates the location record for the specified location. Only site users can update records. Missing fields retain existing values or are set to default values.
| • | allowfrom=IP address/wildcard (zero or more addresses, separated by semicolons or linefeeds) |
| • | loctype=0|1 (0=system client connections, 1=browser client connections) |
| • | email=address (useful for password recovery for browser clients) |
|
putsrc
|
Updates the source record for the specified source ID. Only site users can update records. Missing fields retain existing values or are set to default values.
| • | sourcetype=0|1|2 (0=network port, 1=directory path, 2=email) |
| • | source=value (port number, directory path, or email address; for ports, leave blank to auto-assign the next configured port number) |
| • | wildcard=value (file wildcard(s) for directory path sources, i.e. *.pdf;*.txt) |
| • | allowfrom=IP address/wildcard(s) (for network ports), or linefeed-delimited list of valid From email addresses or domains (email sources) |
| • | targets=job targets (each target specified as tab-delimited locationID and deviceID, multiple targets delimited by linefeeds |
| • | emserver=imap server (use ssl: prefix for IMAPS. Append :port if a non-standard port is required (993 for IMAPS, 143 for IMAP) |
| • | emsubjectauth=text (subjects must have text to for email to be processed) |
| • | empoll=integer (seconds to wait between polls, 0 will attempt to use IMAP IDLE) |
|
submitfile
|
Submits a server-side file to one or more target devices. The file may have been previously uploaded with the putfile endpoint. The target devices are specified as a semicolon-delimited list of locid:devid values. The response is plain text, either a job ID or an error message in the format "Error: message".
file=filename (a server-side file name, such as what is returned by "putfile")
title=title (used as the title attribute of the job, and also a pseudo filename for the recipient)
targets=list (a list of targets locid:devid[;locid:devid;...])
|
|