PaperCut Device REST Web Service API

PaperCut Device REST Web Service API v1
Contents
1 Introduction _________________________________________ 2
2 Using REST APIs ______________________________________ 2
2.1 URIs _________________________________________________ 2
2.2 Representations (Content Types) ______________________________ 2
2.3 Errors and Status codes ____________________________________ 3
3 Security ____________________________________________ 3
4 API Versioning _______________________________________ 3
5 Resources / APIs ______________________________________ 4
5.1 Devices List (GET /rpc/api/rest/device/1/) __________________ 4
5.1.1 Request Query Parameters ___________________________________________ 4
5.1.2 Response Data ___________________________________________________ 4
5.1.2.1 Example JSON Data ____________________________________________ 4
5.1.2.2 Example XML Data ____________________________________________ 5
5.1.3 Example URIs ___________________________________________________ 5
5.2 Device (GET /rpc/api/rest/device/1/<name>) ________________ 6

5.2.1 Response Data ___________________________________________________ 6
5.2.1.1 Example XML Data_____________________________________________ 7
5.2.1.2 Example JSON Data ____________________________________________ 7
5.2.2 Example URIs ___________________________________________________ 8
Revision History
Date
March 27 2014
Author
Geoff Smith
Change
Add optional address field to returned device details
Copyright 2014 PaperCut Software International Pty. Ltd., All Rights Reserved
PaperCut Device REST Web Service API
v2014-07-01
1 Introduction
This document outlines the PaperCut Device REST Web service API that provides a simple
interface for retrieving information about the devices registered to the PaperCut application.
This is available in PaperCut MF version 10.7 or higher.
This interface is commonly used by copier vendors or third parties to provide a single-signon for embedded MFP applications. PaperCuts MFP embedded software controls access to
MFP devices by restricting access to the device until the user successfully authenticates with
PaperCut.
To provide a seamless single-sign-on experience any other MFP applications require the
details of the currently logged-in user (e.g. their username or email address). This
information is now available through this Device REST API.
If you have any questions please contact PaperCut support (support@papercut.com).
2 Using REST APIs

REST (Representational State Transfer) is an approach to creating APIs based on the core
web technologies like HTTP. All resources available in the API are located at URIs that can
be retrieved using any tool, language or platform that can make HTTP requests.
2.1 URIs
REST URIs in PaperCut take the following form:
http://server:port/rpc/api/rest/<api>/<version>
The <version> is used to indicate the version of the API.
For example the Device API URIs are located at:
http://server:port/rpc/api/rest/device/1
2.2 Representations (Content Types)

PaperCut REST APIs support 2 content types for data we generally recommend the JSON
format.
Representation
JSON
(javascript object
notation)
Requested using
Requested using one of:
application/json in the HTTP Accept header
.json file extension
XML
Requested using one of:

application/xml in the HTTP Accept header
.xml file extension
The standard REST way to request a particular content-type/representation is to use the

Accept HTTP header. The Accept header tells the server what content types it supports.
2 of 8
v2014-07-01
To request the XML representation set the Accept header to: Accept: application/xml. To
request the JSON representation set the Accept header to: Accept: application/json.
Setting the Accept header is not always convenient (e.g. when making a request with a
web browser). An alternative way to request a particular representation is to append the
.xml or the .json extensions to the request. Examples of this are given in the Example
URIs sections below.
2.3 Errors and Status codes

Standard HTTP error codes are used to indicate status:
Code
200
Description
Success.
404
Resource not found. This indicates that the requested resource

does not exist.
403
Forbidden. Indicates that security restrictions have disallowed the

request. Check that PaperCut is configured to accept requests from
your network address. For more information see Section 3 Security
below.
Internal server error. This indicates an unexpected server error has
occurred. Please contact PaperCut support if you encounter this.
500
3 Security
Security is important to PaperCut and the device APIs can include some information that
should not be available to unauthorized users. For this reason the PaperCut Device REST
API is only accessible from a pre-defined network address / IP address. By default
PaperCut will only allow requests from localhost (or 127.0.0.1).
If a request is made to these APIs from an unauthorized address the request is denied with a
HTTP status of 403 (Forbidden).
To allow client to call these APIs from other machines, add their IP addresses to the list of
authorized addresses. To do this:
Login to PaperCut as an administrator

Navigate to the Options->General tab
Locate the Security section towards the bottom of the page.
Add the required network address to the Allowed Web Services callers option.
Multiple addresses can be separated by commas. To enter a full subnet range the
following convention can be used: 192.168.1.0/255.255.255.0.
Press Apply to save the changes.
4 API Versioning
This document describes the device REST API version 1. The version number of the API is
encoded in the URI of the API (note the 1 in the API URI below).
3 of 8
v2014-07-01
http://server:9191/rpc/api/rest/device/1/
If there is a need to break compatibility the version number will be increased and the URI
changed to the new version. The old API version will continue to exist.
5 Resources / APIs
All PaperCut device resources are located under the following URIs, one for HTTP and the
other for HTTPS.
HTTP:
http://papercut-server:9191/rpc/api/rest/device/1
HTTPS: https://papercut-server:9192/rpc/api/rest/device/1
5.1 Devices List (GET /rpc/api/rest/device/1/)

The devices list retrieves the list of devices registered with the PaperCut server.
5.1.1 Request Query Parameters

Parameter
type
Description
Filters the list of devices to the list to devices of the given type.
Examples include:
SHARP_OSA For Sharp MFPs
TOSHIBA For Toshiba MFPs
COPICODE_IP For CopiCode IP terminals
serialNumber
Filters the list of devices to the device with the given serial number.
5.1.2 Response Data

This returns a list of devices matching the request.
See section 5.2.1 Response Data for more details explanation of the device data formats.
5.1.2.1 Example JSON Data

This JSON example shows a list containing 2 devices with the minimum data fields
populated.
[
{
"name" : "MyDevice1",
"type" : "DEVICE_TYPE",
"link" : http://server:9191/rpc/api/rest/device/1/MyDevice1
},
{
"name" : "MyDevice2",
4 of 8
v2014-07-01
"link" : http://server:9191/rpc/api/rest/device/1/MyDevice2
}
]
This JSON example shows an empty list containing no devices.

[]
5.1.2.2 Example XML Data

This XML example shows a list containing 2 devices with the minimum data fields populated.
<devices>
<device>
<name>MyDevice1</name>
<type>DEVICE_TYPE</type>
<link>http://server:9191/rpc/api/rest/device/1/MyDevice1</link>
</device>
<device>
<name>MyDevice2</name>
<link>http://server:9191/rpc/api/rest/device/1/MyDevice2</link>
</device>
</devices>
This XML example shows an empty list containing no devices.

<devices/>
5.1.3 Example URIs

To list all devices:
http:// server:9191/rpc/api/rest/device/1/
To list all devices in JSON format:
http:// server:9191/rpc/api/rest/device/1/.json
To list all devices in XML format:
http:// server:9191/rpc/api/rest/device/1/.xml
To list all devices of type SHARP_OSA in JSON format:
http:// server:9191/rpc/api/rest/device/1/?type=SHARP_OSA
5 of 8
v2014-07-01
To list devices with serial number 12345 and of type SHARP_OSA:

http:// server:9191/rpc/api/rest/device/1/?type=SHARP_OSA&serialNumber=1234
5.2 Device (GET /rpc/api/rest/device/1/<name>)

This returns the device details for a single device. The device name in the URL must be
appropriately URL encoded. If the device names contain non ASCII characters they should
be URL encoded in UTF-8.
5.2.1 Response Data

If the given device does not exist, a HTTP 404 error code is returned. If the device exists the
data returned is described here. The same structure applies to both the XML and JSON
formats.
The device contains the following info:
Parameter
name
Description
The device name as it appears in the PaperCut interface
type
The type of the device. Examples of these types include:

SHARP_OSA For Sharp MFPs
TOSHIBA For Toshiba MFPs
COPICODE_IP For CopiCode IP terminals
etc
link
The URI that can be used to access the device resource. The URI
will be correctly URL encoded in UTF-8.
address
(optional)
serialNumber
(optional)
The hostname or IP address of the device if its known. If not

known, this field will not be returned.
The serial number of the device if its known.
If the serial number is not known, this field will not be returned.
loggedInUser
(optional)
The details of the logged in user.

If no user is currently logged in this field is not returned. See the
Device User structure below.
The device user structure describes the user that is currently logged into the device. If a
user is logged into the device this data is populated in the loggedInUser field of the device.
Parameter
username
Description
The username of the user.
fullName
(optional)
email
(optional)
cardNumber
The users full name. If not known, this field is not returned.
The users email address. If not known this field is not returned.
The users card/ID number. If not known this field is not returned.
6 of 8
(optional)
office
(optional)
department
(optional)
v2014-07-01
The users office. If not known this field is not returned.

The users department. If not known this field is not returned.
5.2.1.1 Example XML Data

This section shows some example data in XML format.
Example for a device with all fields populates, including details of the logged in user:
<device>
<name>MyDevice</name>
<link>http://server:9191/rpc/api/rest/device/1/MyDevice</link>
<serialNumber>12345</serialNumber>
<address>10.1.1.12</address>
<loggedInUser>
<username>john</username>
<fullName>John Smith</fullName>
<email>john.smith@domain.com</email>
<cardNumber>12345</cardNumber>
<office>City Office</office>
<department>Administration</department>
</loggedInUser>
</device>
Example for a device with the minimum data populated (i.e. no logged in user):
<device>
<name>MyDevice</name>
<link>http://server:9191/rpc/api/rest/device/1/MyDevice</link>
</device>
5.2.1.2 Example JSON Data

This section shows some example data in JSON format.
Example for a device with all fields populates, including details of the logged in user:
{
"name" : "MyDevice",
"link" : "http://server:9191/rpc/api/rest/device/1/MyDevice",
"serialNumber" : "12345",
"address" : "10.1.1.12",
"loggedInUser" : {
"username" : "john",
"fullName" : "John Smith",
7 of 8
v2014-07-01
"email" : "john.smith@domain.com",
"cardNumber" : "12345",
"office" : "Administration"
"department" : "12345"
}
}
Example for a device with the minimum data populated (i.e. no logged in user):
{
"name" : "MyDevice",
"link" : "http://server:9191/rpc/api/rest/device/1/MyDevice"
}
5.2.2 Example URIs

To retrieve a device named MyDevice:
http:// server:9191/rpc/api/rest/device/1/MyDevice
To retrieve a device named MyDevice in XML format:
http:// server:9191/rpc/api/rest/device/1/MyDevice.xml
To retrieve a device named MyDevice in JSON format:
http:// server:9191/rpc/api/rest/device/1/MyDevice.json
8 of 8

PaperCut Device REST Web Service API

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

PaperCut Device REST Web Service API

Caricato da

Copyright:

Formati disponibili

PaperCut Device REST Web Service API v1

5.2 Device (GET /rpc/api/rest/device/1/<name>) ________________ 6