PaperCut Device REST Web Service API v1

Full text

(1)

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 Author Change

(2)

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-sign-on for embedded MFP applicatisingle-sign-ons. PaperCut’s MFP embedded software csingle-sign-ontrols 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 Requested using JSON

(javascript object notation)

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.

(3)

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 Description

200 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.

500 Internal server error. This indicates an unexpected server error has occurred. Please contact PaperCut support if you encounter this.

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).

(4)

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 Description

type 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",

(5)

"type" : "DEVICE_TYPE",

"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> <type>DEVICE_TYPE</type> <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:

(6)

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 Description

name 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) The hostname or IP address of the device if it’s known. If not known, this field will not be returned. serialNumber

(optional)

The serial number of the device if it’s 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 Description

username The username of the user. fullName

(optional)

The user’s full name. If not known, this field is not returned. email

(optional)

The user’s email address. If not known this field is not returned. cardNumber The user’s card/ID number. If not known this field is not returned.

(7)

(optional) office (optional)

The user’s office. If not known this field is not returned. department

(optional) The user’s 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> <type>DEVICE_TYPE</type> <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> <type>DEVICE_TYPE</type>

<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", "type" : "DEVICE_TYPE", "link" : "http://server:9191/rpc/api/rest/device/1/MyDevice", "serialNumber" : "12345", "address" : "10.1.1.12", "loggedInUser" : { "username" : "john",

(8)

"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", "type" : "DEVICE_TYPE", "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:

Figure

Updating...

References

Updating...