Understand Blimps API Requests and Timestamping

Summary

Learn how to retrieve data from Box+Dice using the Blimps API, including how to request specific fields, handle pagination, and retrieve only updated records using timestamps.

This article covers:

• About the Blimps API
• Load Contacts from Box+Dice using the Blimps API

About the Blimps API

The Blimps API allows client applications to load data from Box+Dice in an efficient and controllable way.

It supports:

• Retrieving multiple resources in one request
• Returning only specific fields
• Incremental loading using timestamps, so only new or updated data is returned

This reduces payload size and improves synchronisation performance.

Load Contacts from Box+Dice using the Blimps API

You can use the Blimps API to retrieve Contacts from Box+Dice in batches and then check for new or updated records using timestamps.

To retrieve Contacts with only the id and email fields, make the following request:

Make a request to get the Contacts and get just the id and email, we would make the request

$ curl -u 'admin:password' -H 'Content-Type: application/json' -d '{"contacts":{"fields":"id,email"}}' http://example.boxdice.com.au/blimps/load 

The server will respond with only the first 1000 contact records, to get the rest you will need to look at the "Content-Range" HTTP response headers:

The "ts" stands for time stamp.  The format of the time stamp (ts) numbers is [from]-[to]/[last]. To get the next segment of 1000 contacts you need to get the :to value (1134) and increment by +1 (1135). Add this value to the request header "Range" in the next request to Blimps:

$ curl -u 'admin:password' -H 'Range: ts=1135' -H 'Content-Type: application/json' -d '{"contacts":{"fields":"id,email"}}' http://example.boxdice.com.au/blimps/load

The server will respond with another 1000 contacts and the HTTP response header:

1135-2284/37304

Again you make another request to Blimps with the header "Range ts=2285". You repeat this until [to] is equal to [last] (37304 = 37304), e.g.

37304/37304

You can now make regular requests (once per hour) to blimps to look for updates and creates (not deletes) by incrementing the ts +1 (37305):

$ curl -u 'admin:password' -H 'Range: ts=37305' -H 'Content-Type: application/json' -d '{"contacts":{"fields":"id,email"}}' http://example.boxdice.com.au/blimps/load

Should there be no changes, you will receive a 304 response (not modified) and no data and no "Content-Range" HTTP header. 
 
If a contact is changed you will receive content and a new "Content-Range" header:

Again the [to] is equal to the [last] so you do not need to make further requests. The next request you make should increment the Range header by +1, e.g "Range ts=37306"