C.2. Web Services

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

Note

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.10, “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"
    }
  }
}