Easy Insight Logo
Easy Insight Logo
Drag. Drop. Done. Business Intelligence Made Easy.

Table of Contents

What is the Easy Insight REST API?

The Easy Insight REST API is a simple REST API for publishing data into Easy Insight.

How do I authenticate?

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).

How do I make requests?

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.

What API calls are available?

You can make the following requests:

  • https://www.easy-insight.com/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.
  • https://www.easy-insight.com/app/xml/defineCompositeDataSource -- creates or updates a composite data source containing joins between multiple other data sources you have already defined.
  • https://www.easy-insight.com/app/xml/addRows -- adds new rows of data to a data source.
  • https://www.easy-insight.com/app/xml/replaceRows -- replaces the current contents of a data source with a new set of rows.
  • https://www.easy-insight.com/app/xml/replaceRows -- updates certain rows within the data source based on the specified where clauses.

How about a simple example?

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 https://www.easy-insight.com/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.

Response codes reference

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:

  • 200 -- everything's good, call worked
  • 400 -- something was wrong with the request
  • 401 -- bad credentials
  • 500 -- server error

defineDataSource reference

XML POST to https://www.easy-insight.com/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.

defineCompositeDataSource reference

XML POST to https://www.easy-insight.com/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>

addRows reference

XML POST to https://www.easy-insight.com/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>
        

replaceRows reference

XML POST to https://www.easy-insight.com/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>
        

updateRows reference

XML POST to https://www.easy-insight.com/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>
        

What if I have a lot of data to add?

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 https://www.easy-insight.com/app/xml/beginTransaction passing an operation:

  • add - data is appended to the data source named.
  • replace - data replaces the current data in the data source.


    <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 https://www.easy-insight.com/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 https://www.easy-insight.com/app/xml/commit :


    <commit>
    <transactionID>Given Transaction ID</transactionID>
    </commit>