SOAP API¶

Prerequisites¶

The SOAP API of LiveConfig is accessible at the URL /liveconfig/soap. SOAP calls must be encoded in document/literal style (not in RPC/encoded style!).

You also need

• a LiveConfig Standard® or LiveConfig® Business license (the SOAP API is not available with Basic or Light license)

• access to the LiveConfig® admin account

• having configured a SOAP password for the admin account (see next section)

Authentication¶

All SOAP methods require the submission of an auth parameter, which contains the user name, a timestamp and the SOAP token. The token is a base64-encoded HMAC-SHA1 checksum on the string “LiveConfig”, the user name, the invoked method name and a time stamp; the SOAP password is used as key.

To set the SOAP password, run liveconfig --init and set the environment variable LCINITSOAP to your desired password:

#> LCINITSOAP="SoAp_pAsSwOrD" liveconfig --init

This example shows the creation of the auth parameter in PHP:

<?php
$user = 'admin';         # user name
$pass = 'PaSsWoRt';      # SOAP password
$func = 'TestSayHello';  # SOAP method to call

# create timestamp, e.g. '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# generate token:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts,
                                 $pass,
                                 true
                                )
                      );

# generate "auth" parameter:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token
             );
?>

The timestamp in the auth parameter must not differ more than 15 minutes from the LiveConfig server - otherwise you get an error message. The timestamp has to be given in UTC/GMT timezone.

Running SOAP methods with customer permissions

You can call all SOAP methods also with the permissions of any customer. This can be useful when working e.g. with reseller accounts.

In this case, the (encoded) customer ID needs to be added before hashing, and the field customer be added to the auth parameter.

Example in PHP how to run a SOAP method as a specific customer:

<?php
$user = 'admin';         # user name
$pass = 'PaSsWoRt';      # SOAP password
$func = 'TestSayHello';  # SOAP method to call
$cust = 'c9R4hQp.T-rF';  # encoded customer id

# create timestamp, e.g. '2009-12-07T11:05:00.000Z'
$ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";

# generate token:
$token = base64_encode(hash_hmac('sha1',
                                 'LiveConfig' . $user . $func . $ts . $cust,
                                 $pass,
                                 true
                                )
                      );

# generate "auth" parameter:
$auth = array('login'     => $user,
              'timestamp' => $ts,
              'token'     => $token,
              'customer'  => $cust
             );
?>

WSDL Description¶

LiveConfig provides a WSDL description of all permitted methods and accompanying data types for a particular user. For this, append ?wsdl as well as the user name and the SOAP password to the SOAP URL.

The following example shows the creation of a SOAP client in PHP based on a WSDL file:

<?php
$user = 'admin';         # User name
$pass = 'PaSsWoRt';      # SOAP password

# Construct WSDL URL
$url = 'https://your.liveconfig.server:8443/liveconfig/soap'
      .'?wsdl'  # request WSDL
      .'&l=' . urlencode($user)
      .'&p=' . urlencode($pass);

# Create SOAP client
$client = new SoapClient($url,
                         array('style' => SOAP_DOCUMENT,
                               'use'   => SOAP_LITERAL,
                              )
                        );
?>

Example Code¶

In this section you find some examples for using the SOAP API with common program languages.

PHP¶

PHP has native SOAP support. The only prerequisite is that the SOAP module is loaded (when compiling PHP by yourself, use the option --enable-soap). If SOAP support is enabled can be seen in the output of phpinfo():

The following example program shows all necessary steps to send a SOAP request to LiveConfig:

<?php

  # Configuration parameters:
  $user = 'admin';
  $pass = 'PaSsWoRd';
  $url  = 'https://your.liveconfig.server:8443/liveconfig/soap';

  # Construct WSDL URL
  $wsdl_url = $url
             .'?wsdl'
             .'&l=' . urlencode($user)
             .'&p=' . urlencode($pass);

  # Create SOAP client
  $client = new SoapClient($wsdl_url,
                           array('style'    => SOAP_DOCUMENT,
                                 'use'      => SOAP_LITERAL,
                                )
                          );

  # Construct SOAP token:
  $ts = gmdate("Y-m-d") . "T" . gmdate("H:i:s") . ".000Z";
  $token = base64_encode(hash_hmac('sha1',
                                   'LiveConfig' . $user . 'TestSayHello' . $ts,
                                   $pass,
                                   true
                                  )
                        );

  $auth = array('login'     => $user,
                'timestamp' => $ts,
                'token'     => $token);

  $params = array('auth'      => $auth,
                  'firstname' => 'John',
                  'lastname'  => 'Doe');

  try {
    $response = $client->TestSayHello($params);
  } catch (SoapFault $soapFault) {
    die("Error while calling Web Service: " . $soapFault->faultstring . "\n");
  }

  echo "Response: " . $response->greeting . "\n";

?>

SOAP Reference¶