General usage of the API

Several API-calls are available, and depending on the specific API-call you may:

  • Supply data into the API-call using GET/POST-variables.
  • Supply data into the API-call using an XML-structure.

Depending on the API-call, or how the API is called the response can be different too. Available responses are:

  • Response in plain and simple XML.
  • Response in JSON format. By providing the optional GET/POST-parameter: (?format=json) or the additional < format >json< /format > tag.
  • Response without any formatting or structure.

The XML-data can be submitted in two different ways:

  • The xmlfile approach.
  • The xmlstring approach.

The maximum size for posting a dataset into our API is currently set to 16 megabytes. Please drop us a line if you intend to offer larger datasets.

Notes worth reading

  • We have done our utmost best to allow you to supply variables and parameters to the API in many ways. However it is important to know that variables in XML always trump those supplied through GET/POST.
  • Be sure to use the https protocol for the location of your xmlfile. Mandatory SSL encryption for hosted XML-files has been planned for 2014.

Basic Submit method #1: Using the xmlfile approach

Submitting XML as a local file.
Save all the necessary data in a temporary XML file that can be accessed by Acumulus on a remote location. Suppose you have an XML-file ready for processing by the Acumulus API at the following location:

https://www.yourwebshop.com/somefolder/yourfile.xml

Assuming the API-call allows for XML-data to be processed you can submit your XML-file using the following url:

https://api.sielsystems.nl/acumulus/stable/path/to/api_call_used.php?xmlfile=https://www.yourwebshop.com/somefolder/yourfile.xml

Basic Submit method #2: Using the xmlstring approach

Post all the data staight into the API. For example, use cURL and PHP. This requires cURL on your webserver to function properly. You are free to use other methods as our example below is only intended as a reference.

<?php
    $xml_string = "<myxml>......</myxml>";
    $url = "https://api.sielsystems.nl/acumulus/stable/path/to/api_call_used.php";
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, "xmlstring=$xml_string");
    curl_setopt($ch, CURLOPT_TIMEOUT, 10);
    curl_exec($ch);
    curl_close($ch);
?>

Please note that you will need to properly escape your XML-control characters. The API does not sanitize this for you. If you do not escape the & into &amp; the supplied XML will be considered invalid. The same is applicable to < and > which need escaping too.

Using below line may help you prevent this from happening.

<?php
    htmlentities($value_xmlfield, ENT_XML1, 'UTF-8');
?>

Alternatively you can try to use php urlencode on your entire xml_string.

Subscribe to Acumulus API RSS