The PrintFleet Enterprise web services are RESTful services. As such, everything is represented as a resource, upon which different actions can be performed. Actions are represented using HTTP verbs such as GET, POST, PUT, and DELETE, and responses are indicated with HTTP status codes. As a general guideline, GET = retrieve, POST = update, PUT = create, and DELETE = remove.

Quick Start

1. Log in to the web UI
2. Check that you're logged in by using the GET /auth method. You should see a response listing your userid, name, permissions, etc.
3. Try listing all groups using GET /groups
4. One of the main ways to get data from the system is POST /dataviews. Try using the example request, but note on a large system using the root group (default) will be slow so you may want to choose a smaller group.

Authentication

Calls against the web service API should send a standard HTTP Basic Authentication header, with a username and password of a valid PFE user. It is recommended to create a specific user for the API to use so the password doesn't have to be shared with a real user and it's easier to identify API usage. Note that by default HTTP authentication is only allowed over SSL (https://) for security reasons.

To create an Authorization header manually, first combine the user name and password into a single string with a colon separating the two, and then base64 encode it. For example, the username "apiuser" and password "secret" are transformed to "apiuser:secret", and the Base64 of that is "YXBpdXNlcjpzZWNyZXQ=". Sending this as a raw HTTP header:

Authorization: Basic YXBpdXNlcjpzZWNyZXQ=

Authentication During Development

Technically the API will also accept an existing web session (via cookie) as authentication, which is how the service is used when the PrintFleet Enterprise web interface (aka PrintFleet Optimizer) calls it. This means online on the live PFE server), you can simply log in to the web interface first.

for the purposes of testing this API from a browser (which you can do if you are viewing this documentation

Since it is only possible to obtain a session cookie by logging in to the regular PrintFleet Enterprise web user interface, we recommend developers sticking to regular HTTP authentication for use of the API.

API Keys

This section describes API keys; when to use them, how to acquire them, and how to use them with the PrintFleet REST API.

Acquiring API Keys

Please contact PrintFleet Technical Support with the following information:

1. Contact Details (Name, Company, Phone, E-mail)
2. PFE Server URL you're requesting access for
3. Purpose of the API use (basic description of what you're trying to accomplish in accessing the API)

Using API Keys

API keys are being introduced by PrintFleet to secure and understand the usage patterns of our users. This will enable us to optimize and evolve our API's for the benefit of our users. As a first phase to this implementation, a key is necessary to use 3.6.0 and all future API versions. Applications built against versions prior to 3.6.0 will continue to work, and the requirement of keys is not currently applicable to prior versions.

To take advantage of 3.6.0 and all future API versions, please see Acquiring API Keys.

An API key can be used in one of two ways:

1. Raw HTTP Header:

   X-API-KEY: {apikey}

2. Query String Parameter:

   ?api_key={apikey}

If you try to access 3.6.0 (and all future versions) of the API without specifying or providing a valid key, you will receive an HTTP 403 Forbidden response with a message indicating the failure.

Format

Unless otherwise specified, all requests and responses are formatted using JSON. Requests should send both the Content-Type: application/json and Accepts: application/json headers.

Versioning

All API calls are versioned, according to the version of the PrintFleet Enterprise release. Each new release technically has a new API version, however, please check the release notes to see if anything in the interface has actually changed.

Since each version is supported for some time after release of newer versions, it is not necessary to update your application immediately. Please check the release notes for a list of supported and deprecated API versions.

The base URL for any call is always /restapi/version/, so for example:

GET /restapi/3.2.0/auth

Errors

Errors are indicated by a HTTP response code. HTTP 200 OK is returned for a successful query, and other response codes are returned depending on the problems with the specific service.

URL Encoded String Parameters

All string parameters for any API request should be URL encoded to ensure special characters are transmitted and handled correctly. Failure to do so may result in undesired or incomplete results.