API Reference: Batching Requests

Sometimes your application needs to perform many requests against the Solve API. For instance, obtain contact details for a set of IDs, or, create activities for each.

With a Batch request you can make a single call to the API containing all of the requests at once which avoids the HTTP overhead of making the requests individually.

Currently the number of requests in a batch is limited to 100. Each call within a batch is still counted against the API quota.

Format

A batch request is an HTTP POST “container” request to https://secure.solve360.com/batch with the real calls included as nested HTTP requests. The batch request itself must have the Content-Type header set to multipart/mixed, while all the nested request have Content-Type: application/http. The body of each part is a complete HTTP request with headers, URL and body.

Headers of the batch request apply to every nested request in the batch, unless overwritten. This makes it possible to provide authentication header only once - for the outer batch request itself.

Each nested HTTP request is treated and processed by Solve API servers as a separate HTTP call.

Example Batch Request

POST /batch HTTP/1.1
Host: secure.solve360.com
Authorization: Basic E3VwcGEwoid654JhZGEuY29tOnM2VDBsNURlQzdmYW04aDNaMG4zNGRtjkOhWjBmMzJicWJVjiOijkl=
Content-Type: multipart/mixed; boundary=====1340674896===
Content-Length: 1220
Connection: close

--====1340674896===
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID:

GET /contacts/479038 HTTP/1.1
Content-Type: application/xml
Accept: application/xml
Content-Length: 0


--====1340674896===
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID:

GET /contacts/299430 HTTP/1.1
Content-Type: application/xml
Accept: application/xml
Content-Length: 0


--====1340674896===
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID:

POST /contacts/ HTTP/1.1
Content-Type: application/xml
Accept: application/xml
Content-Length: 116

<?xml version="1.0" encoding="utf-8"?>
<request><firstname>Alex</firstname><lastname>Steshenko</lastname></request>

--====1340674896===--

Example Batch Response

HTTP/1.1 200 OK
Date: Sat, 16 Mar 2013 18:22:36 GMT
Server: Apache
Http-X-Solve360-Api-Call-Limit: 584/12000
Access-Control-Allow-Origin: *
Content-Length: 2387
Connection: close
Content-Type: multipart/mixed; boundary=solve360batch_1277289553===

--solve360batch_1277289553===
Content-Type: application/http
Content-ID:

HTTP/1.1 200
Content-Type: application/xml
Content-Length: 734

<?xml version="1.0" encoding="utf-8"?>
<response><item><id>479038</id><name/><typeid>1</typeid><created>2013-03-15T22:54:27+00:00</created><viewed>2013-03-16T18:17:31+00:00</viewed><updated>2013-03-15T22:54:27+00:00</updated><ownership>299430</ownership><flagged></flagged><fields><lastname label="Last name"></lastname><personalemail label="Personal Email"></personalemail><firstname label="First name"></firstname><businessemail label="Email"></businessemail><creatorid>299430</creatorid><creatorname>John Smith</creatorname><creatordate>1363388067</creatordate></fields></item><activities/><categories/><relateditems/><status>success</status></response>

--solve360batch_1277289553===
Content-Type: application/http
Content-ID:

HTTP/1.1 404
Content-Type: application/xml
Content-Length: 151

<?xml version="1.0" encoding="utf-8"?>
<response><errors><itemisnotfound>Item is not found</itemisnotfound></errors><status>failed</status></response>

--solve360batch_1277289553===
Content-Type: application/http
Content-ID:

HTTP/1.1 201
Location: http://secure.solve360.com/contacts/479043
Content-Type: application/xml
Content-Length: 971

<?xml version="1.0" encoding="utf-8"?>
<response><item><id>479043</id><name>Alex Steshenko</name><typeid>1</typeid><created>2013-03-16T18:22:36+00:00</created><viewed>2013-03-16T18:22:36+00:00</viewed><updated>2013-03-16T18:22:36+00:00</updated><ownership>299430</ownership><flagged></flagged><fields><lastname label="Last name">Steshenko</lastname><personalemail label="Personal Email"></personalemail><firstname label="First name">Alex</firstname><businessemail label="Email"></businessemail><creatorid>299430</creatorid><creatorname>John Smith</creatorname><creatordate>1363458156</creatordate><modificatorid>299430</modificatorid><modificatorname>John Smith</modificatorname><modificatordate>1363458156</modificatordate></fields></item><activities/><categories/><relateditems/><status>success</status></response>

--solve360batch_1277289553===--

cURL Example

cURL does not allow us to play with multipart/mixed requests nicely, but there is a workaround to try batch API with it:

1) Create a file, request.txt with all the children requests you want:

-----12345abcde
Content-Type: application/http

GET /contacts HTTP/1.1


-----12345abcde
Content-Type: application/http

GET /companies HTTP/1.1


-----12345abcde--

In this case we make a request to get all contacts and another one to get all companies. There is no payload, just URLs. It is critical that all line endings in the file are in CRLF (\r\n) format, otherwise HTTP will not be considered valid.

2) Execute curl command, using your Solve account email and the API token, as follows:

curl -u 'your360account@example.com:E7t0l5DeC7f123jkln34dm0laZ0f3UIO78baf2' -X POST -H "Content-Type: multipart/mixed; boundary=---12345abcde" --data-binary @request.txt https://secure.solve360.com/batch

PHP Library

Solve’s PHP library has been extended to support the new Batch functionality. You can switch the service into “batch mode” and then call methods as usual:

$solve360Service->enableBatchMode(); // enables batch mode
$key1 = $solve360Service->getContact(479038); // schedules a GET contact request
$key2 = $solve360Service->getContact(299430);
$key3 = $solve360Service->addContact(['firstname' => 'Alex', 'lastname' => 'Steshenko']);
$responses = $solve360Service->requestBatch(); // here the batch HTTP request happens

$contact1 = $responses[$key1]; // we can now retrieve the exact response
$contact2 = $responses[$key2]; // by the keys we were given earlier
$newContact = $responses[$key3];

echo $contact2->item->name; // outputs name of contact 299430
echo $newContact->item->id; // echoes new contact id

$solve360Service->disableBatchMode(); // proceed in the normal regime from now