The Easy Insight Legacy XML API is an XML API for publishing data into Easy Insight. This API is outdated and we recommend using our newer JSON API, found here.
The API uses basic HTTP authentication. You can either use your Easy Insight username and password or API key and secret key (recommended for security).
The specifics will depend on your programming language, but as a general rule, you'll be making HTTP POSTs of XML to the URLs listed below. Make sure to set 'Content-Type' and 'Accept' headers to 'application/XML' to identify the request and response formats.
You can make the following requests to https://www.easy-insight.com/:
For this first example, we'll create a data source with three fields and publish a row of data into the data source. First, XML for creating the data source, which will be a POST to /app/xml/defineDataSource.
<defineDataSource>
<dataSourceName>Sample Order Database</dataSourceName>
<fields>
<field dataType="grouping">
<key>Customer</key>
</field>
<field dataType="measure">
<key>Amount</key>
</field>
<field dataType="date">
<key>OrderDate</key>
</field>
</fields>
</defineDataSource>
This call returns:
<response>
<code>200</code>
<dataSourceKey>A Unique Key for the Data Source</dataSourceKey>
</response>
You can use the value returned from dataSourceKey as a unique identifier for publishing data into the data source. Next, we publish data source into the data source by making a POST to https://www.easy-insight.com/app/xml/addRows.
<rows dataSourceName="Sample Order Database">
<row>
<Customer>Acme</Customer>
<Amount>500</Amount>
<OrderDate>2010-11-12T12:00:00</OrderDate>
</row>
</rows>
The result of these calls will be a data source inside of Easy Insight with the fields of Customer, Amount, and OrderDate, containing one row of data.
With every call, there is a code tag returned as part of the response XML. More information is typically available in the rest of the XML, but as a general reference:
XML POST to /app/xml/defineDataSource -- creates or updates a data source. If the data source already exists, returns a unique key you can use to pass data into the data source.
<defineDataSource>
<dataSourceName>Your Data Source Name</dataSourceName>
<fields>
<field dataType="grouping">
<key>customer</key>
<name>Customer</name>
</field>
<field dataType="measure">
<key>orderAmount</key>
<name>Order Amount</name>
</field>
<field dataType="date">
<key>orderdate</key>
<name>Order Date</name>
</field>
</fields>
</defineDataSource>
Valid dataType attributes are grouping, measure, date, tags, latitude, longitude, and postal.
XML POST to /app/xml/defineCompositeDataSource -- creates or updates a data source. If the data source already exists, returns a unique key you can use to pass data into the data source.
<defineCompositeDataSource>
<dataSourceName>Your Data Source Name</dataSourceName>
<dataSources>
<dataSource>Contained Data Source Name or API Key</dataSource>
</dataSources>
<connections>
<connection>
<sourceDataSource>Source Data Source Name or API Key</sourceDataSource>
<targetDataSource>Target Data Source Name or API Key</targetDataSource>
<sourceDataSourceField>Join Field on the Source Data Source</sourceDataSourceField>
<targetDataSourceField>Join Field on the Target Data Source</targetDataSourceField>
</connection>
</connections>
</defineCompositeDataSource>
XML POST to /app/xml/addRows -- adds new rows of data to a data source.
<rows dataSourceName="Your Data Source Name">
<row>
<customer>Acme</customer>
<orderamount>500</orderamount>
<orderdate>2010-11-12T12:00:00</orderdate>
</row>
</rows>
XML POST to /app/xml/replaceRows -- replaces the current contents of a data source with a new set of rows.
<rows dataSourceName="Your Data Source Name">
<row>
<customer>Acme</customer>
<orderamount>500</orderamount>
<orderdate>2010-11-12T12:00:00</orderdate>
</row>
</rows>
XML POST to /app/xml/updateRows -- updates certain rows within the data source based on the specified where clauses.
<update>
<rows dataSourceName="Your Data Source Name">
<row>
<customer>Acme</customer>
<orderamount>500</orderamount>
<orderdate>2010-11-12T12:00:00</orderdate>
</row>
</rows>
<wheres>
<where whereType="string">
<key>customer</key>
<value>Acme</value>
</where>
</wheres>
</update>
<update>
<rows dataSourceName="Your Data Source Name">
<row>
<customer>Acme</customer>
<orderamount>500</orderamount>
<orderdate>2010-11-12T12:00:00</orderdate>
</row>
</rows>
<wheres>
<where whereType="day">
<key>orderdate</key>
<year>2010</year>
<day>275</day>
</where>
</wheres>
</update>
If you have a lot of data to add, it probably won't all fit into one XML request. It's best to split it up into multiple requests, using the transactional API. To begin a transactional commit, do an XML POST to /app/xml/beginTransaction passing an operation:
<beginTransaction>
<dataSourceName>Your Data Source Name</dataSourceName>
<operation>add</operation>
</beginTransaction>
The call will return a transaction ID in the response, which you can then use to load data into the data source, as below.
<response>
<code>200</code>
<transactionID>A Unique Key for the transaction</transactionID>
</response>
You can then use that transaction ID to load records just like addRows/replaceRows above, but XML POST to /app/xml/loadRows :
<rows transactionID="Given Transaction ID">
<row>
<Customer>Acme</Customer>
<Amount>500</Amount>
<OrderDate>2010-11-12T12:00:00</OrderDate>
</row>
</rows>
When you are finished, all of the data will be copied into the data source by committing the data with an XML POST to /app/xml/commit :
<commit>
<transactionID>Given Transaction ID</transactionID>
</commit>
