Monday, June 10, 2013

Introducing the Export API

APILast month, a read-only database mirror was added to the infrastructure of the ITRP service. We did that to prepare the infrastructure for some important features that we wanted to add to the service. Another one of these features has now been released. It is the brand new Export API.

This may not sound very exciting, since the Import/Export feature already allowed you to export the data from your ITRP account. There are two reasons why the Export API was added to the already comprehensive set of ITRP APIs.

First, the Export API makes it possible to automate exports. Now you can, for example, prepare a script that periodically exports your data and loads it into your corporate data warehouse.

Second, the Export API allows you to do incremental exports. This means that you could schedule your script to run every night and to only export the records that have been created or updated in the past 24 hours.

In the remainder of this post, I am going to explain how easy it is to use the Export API. Don't worry if you are not a developer; I am not either.

Let's use an example command to explain how you can talk to the Export API and what the options are. Here it is:

 $ curl -u "api-token:x" -F "type=requests" -F "from=20130601"  ""                                                    

The example assumes that we are using cURL to send the command to the Export API. Don't worry if you don't know what cURL is; it is a command line tool that is popular with developers. I am merely explaining this so that you understand why the command starts with curl.

This brings us to authentication. Where it says api-token, you replace that with your personal API Token. You can find your API Token at the end of the Personal Information section in the Settings console. When you click on the little "Reveal" button you will see a long string of characters that acts as a username/password when you contact the API. So do keep your API Token a secret. Note that the Export API only accepts commands from people who have the Account Administrator role, so not just anyone can extract the data from your ITRP account.

Now for the interesting bits. The command asks for an export of Request records. Naturally, you can specify other types of records. And you can specify multiple record types so that you only need one command to export, for example, requests and problems. In that case, you would write: type=requests,problems. You can even specify type=all to export all records from your account. But that would probably be a huge export, which takes us to the next parameter.

By specifying a date in your command, you are telling the API that you want to export only the records that have been created or updated on or after this date. The date in our example is 20130601 or June 01, 2013.

The last bit of the command simply states that you want to send this command to which is the Export API of the ITRP service.

After you have sent this command to the Export API, the export job will start. As soon as it is finished, you will receive an email with a hyperlink to the UTF-8 encoded comma-separated values (CSV) file that contains the request records. Just click on this hyperlink to download the export file to your computer. ITRP automatically encrypts your connection to ensure that the transmission of the data is secure.

Easy right? The real developers among you may want to check out some of the more advanced features that this API offers. You can find them in the Export section of the ITRP developer documentation.