C.2. Web Services

SavaPage uses XML-RPC, JSON-RPC and RESTful API for its public Web Services. Both protocols are Open Standard, lightweight and have support for all major programming and scripting languages.

Note

The range of Web Services will grow upon request. Please tell us if you need extra methods.

C.2.1. XML-RPC

The secure endpoint is: https://savapage:8632/xmlrpc/v1

C.2.1.1. onetime-auth.createToken

With this method a Trusted Third Party (TTP) acquires a one-time token for Web App user authentication.

The requesting User Name and returned Token must be offered to the Web App by hidden HTTP POST input names auth_user and auth_token. The Web App decrypts the token and honours the authentication request if the offered and encrypted Users match and the token is not expired.

 NameTypeDescription

Parameters

apikey

string

The TTP API key as set in the web-login.ttp.apikey configuration property.

 username

string

The User Name to authenticate. See Section 3.1, “Login”.

User Alias mapping is applied.

Returns

token

string

The one-time authentication token holding the encrypted User Name and token creation time.

The expiration criterion in milliseconds is set in the web-login.ttp.token.expiry-msecs configuration property.

Table C.1. XML-RPC method: onetime-auth.createToken


Note

TTP Web App Login authentication must be enabled by setting the web-login.ttp.enable configuration property to Y.

C.2.2. JSON-RPC

The secure endpoint is: https://savapage:8632/jsonrpc/v1

The following configuration properties apply:

Configuration propertyDescription

api.jsonrpc.secret-key

The secret key to be passed as X-Auth-Key HTTP header.

api.jsonrpc.ext.ip-addresses-allowed

A CIDR Set of allowed client IPv4 addresses. When void access is denied for all clients.

Table C.2. JSON-RPC Configuration Properties


See Section 4.10.14.11, “Config Editor” on how to set these items.

The sections below discuss the individual methods. All methods default to the same response layout in case of an error.

JSON-RPC : Basic Error

Figure C.1. JSON-RPC : Basic Error


C.2.2.1. systemStatus

This method returns the system status as enum value. READY indicates the system is ready to use and users have access to the Web App. All other values indicate that user access is denied, because: system SETUP is needed, MAINTENANCE is in progress, or the system is temporarily UNAVAILABLE due to running batch jobs (database backup, user synchronization, database cleanup).

Note

Although the system can have multiple "deny status" at the same time, the single most important status is returned, in the order SETUP, MAINTENANCE, UNAVAILABLE.

JSON-RPC : systemStatus (request)

Figure C.2. JSON-RPC : systemStatus (request)


JSON-RPC : systemStatus (response)

Figure C.3. JSON-RPC : systemStatus (response)


# sample request
curl --request POST --header "X-Auth-Key: 7961b5ec-bee4-11e7-8731-406186940c49" \
     --data '{"jsonrpc":"2.0","id":"reference","method":"systemStatus"}' \
     https://savapage:8632/jsonrpc/v1
 
# sample response
 {
  "jsonrpc" : "2.0",
  "id" : "reference",
  "result" : {
    "data" : {
      "@type" : "enum",
      "value" : "READY"
    }
  }
}

C.2.2.2. authUserSource

This method authenticates an external user against the configured User Source.

JSON-RPC : authUserSource (request)

Figure C.4. JSON-RPC : authUserSource (request)


JSON-RPC : authUserSource (response)

Figure C.5. JSON-RPC : authUserSource (response)


# sample request
curl --request POST --header "X-Auth-Key: 7961b5ec-bee4-11e7-8731-406186940c49" \
     --data '{"jsonrpc":"2.0","id":"reference","method":"authUserSource", \
               "params":{"username":"john","password":"AzFi7I"}}'
     https://savapage:8632/jsonrpc/v1

# sample response
{
  "jsonrpc" : "2.0",
  "id" : "reference",
  "result" : {
    "data" : {
      "@type" : "boolean",
      "value" : true
    }
  }
}
# sample error
{
  "jsonrpc" : "2.0",
  "id" : "reference",
  "result" : false,
  "error" : {
    "code" : -32603,
    "message" : "ldapserver:636 [No route to host (Host unreachable)]",
    "data" : {
      "@type" : "BASIC",
      "reason" : "ldapserver:636"
    }
  }
}

C.2.3. RESTful API

Preview

RESTful Web Services is a Feature Preview that is partly operational and impermanent. The preview is offered to provoke feedback based on real world use. Please tell us your requirements.

The secure endpoint is: https://savapage:8632/restful/v1

Services are described with curl examples.

C.2.3.1. RESTful Admin Services

Access to Admin Services is controlled by Basic HTTP Authentication.

Configuration propertyDescription

api.restful.auth.username

Basic Authentication Username.

api.restful.auth.password

Basic Authentication Password.

api.restful.ip-addresses-allowed

A CIDR Set of allowed client IPv4 addresses. When void access is denied for all clients.

Table C.3. RESTful Admin Services Configuration Properties


C.2.3.1.1. POST /test/echo

curl -k -u admin:password -X POST \
     "https://savapage:8632/restful/v1/tests/echo" \
     -H "Content-Type:text/plain" -d "Hello World!"

# response
Hello World!

C.2.3.1.2. GET /system/version

curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/system/version"

# sample response
SavaPage 1.2.0-rc (Build 20190909)

C.2.3.1.3. GET /documents

# GET JSON info of first 5 documents sorted by creation datetime descending
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents?sort=-created"

# ... sorted ascending
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents?sort=+created"

# GET JSON info of first page chunk of 2 proxy printed documents
# type = all (default) | in | out | pdf | print | ticket

curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents?sort=-created&type=print&limit=2&page=0"

# sample response
[ {
  "id" : 6263,
  "ext_id" : "",
  "type" : "print",
  "title" : "Document A",
  "created" : "2019-09-13T09:18:38+0200",
  "store" : false
}, {
  "id" : 6258,
  "ext_id" : "c5a9dd70e931",
  "type" : "print",
  "title" : "Document B",
  "created" : "2019-09-12T09:49:48+0200",
  "store" : false
} ]

C.2.3.1.4. GET /documents/<id>

# GET JSON info of document id 6272
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents/6272"

# sample response
{
  "id" : 6272,
  "ext_id" : "d2a3a71c11e9",
  "type" : "print",
  "title" : "Invoice 20190248",
  "created" : "2019-09-16T12:29:15+0200",
  "store" : true
}

C.2.3.1.5. GET /documents/ext_id=<ext_id>

# GET JSON info of document with ext_id d2a3a71c11e9
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents/ext_id=d2a3a71c11e9"

C.2.3.1.6. GET /documents/<id>/pdf

# GET stored PDF document 6272
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents/6272/pdf" > 6272.pdf

C.2.3.1.7. GET /documents/ext_id=<ext_id>/pdf

# GET stored PDF document with ext_id d2a3a71c11e9
curl -k -u admin:password -X GET \
     "https://savapage:8632/restful/v1/documents/ext_id=d2a3a71c11e9/pdf" \
     > d2a3a71c11e9.pdf

C.2.3.2. RESTful User Services

Access to User Services is controlled by User ID and UUID.

C.2.3.2.1. POST /documents/<userid>/<uuid>

# Print file "lorem-ipsum.txt" to SavaPage as user "janet" with UUID credentials
curl -v -k -H "Content-Type: multipart/form-data" -H "Accept: application/json" \
     -F "file=@lorem-ipsum.txt" -X POST \ 
      https://savapage:8632/restful/v1/documents/janet/97008e2c-d8b2-11e9-aa13-406186940c49

Important

This print maps to the default Queue /webservice. To exclusively accept RESTful prints from specific IP addresses see Section 4.7.3, “Edit Queue”.