Save data in Box+Dice using the Blimps API

Summary

Learn how to create and update records in Box+Dice using the Blimps API, including how record IDs, client IDs, and combined save requests work.

This article covers:

• About saving data with the Blimps API
• Update existing records
• Create new records
• Create and update records in one request
• Save multiple resource types in a single request

About saving data with the Blimps API

The Blimps save API allows client applications to create new records, update existing records, or do both in a single request.

To save data correctly, you must understand how Box+Dice record IDs, client‑side IDs, and timestamps are used in responses.

Update existing records

When updating existing records, client application needs to use the record ids received from Box+Dice when requesting records.

First, load desired records from Box+Dice:

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

= {"contacts":[{"id":9},{"id":10,"email":"paul@example.com.au"},{"id":11},{"id":12,"email":"heather@example.net.au"},...]}

Then use the Box+Dice record ids to update fields in existing records:

$ curl -u 'admin:password' -H 'Content-Type: application/json' -d '{"contacts":[{"id":11,"email":"adam@example.com.au"},{"id":12,"firstName":"Heather"}]}' http://example.boxdice.com.au/blimps/save

= {"contacts":[{"id":11,"ts":1362387482},{"id":12,"ts":1362387546}]}

Create new records

When creating new records, client application can include ids from the client database to match records and their Box+Dice ids in the response with client ids. The client id can be either a string or a number:

$ curl -u 'admin:password' -H 'Content-Type: application/json' -d '{"contacts":[{"clientId":"xvzf","firstName":"Peter"},{"clientId":"xvzg","firstName":"Mark"}]}' http://example.boxdice.com.au/blimps/save

= {"contacts":[{"clientId":"xvzf","id":4963,"ts":1362388343},{"clientId":"xvzg","id":4964,"ts":1362388343}]}

Create and update records in one request

The Blimps API allows you to create new records and update existing ones in a single save request.

Example: Create one contact and update another

$ curl -u 'admin:password' -H 'Content-Type: application/json' -d '{"contacts":[{"clientId":"xvzf","firstName":"Peter"},{"id":11,"email":"adam@example.com.au"}]}' http://example.boxdice.com.au/blimps/save

= {"contacts":[{"clientId":"xvzf","id":4963,"ts":1362388343},{"id":11,"ts":1362387482}]}

$ curl -u 'admin:password' -H 'Content-Type: application/json' -d '{"contacts":[{"clientId":"xvzf","firstName":"Peter"}],"consultants":[{"id":3,"firstName":"Mark"}]}' http://example.boxdice.com.au/blimps/save

= {"contacts":[{"clientId":"xvzf","id":4963,"ts":1362388343}],"consultants":[{"id":3,"ts":1362392764}]}