Batch Requests

Sometimes you want to perform multiple queries all at once. For example, maybe you need to load a few collections to populate a form. Normally you would need to submit multiple HTTP requests which could be slow.

You POST a map to the /batch endpoint describing the requests you want to submit. The system will process all of your requests at once, and send you back a single result object. The keys of the result will be the same keys you submitted.

Example request using a key-value map of requests to execute in a batch:

curl -H "Authorization: key 1:CVRRGQ58QDX8H5B4W4RAJ978Q" \
     -H "Content-Type: application/json" \
     -X POST \
     -d '
 {
     "t": {
         "method": "POST",
         "url": "/api/tickets",
         "payload": {
             "title": "new-ticket"
         }
    },
    "john": "/api/people/1",
    "img": "/api/people/1/image",
    "parts": "/api/tickets/5/participants"
 }
'
     http://example.com/api/v2/batch

Example response where each response uses the same key you sent in the request:

{
    "t": {
      "headers": {
          "response_code": 201,

      },
      "data": {
         "title": "new-ticket"
         "...": "..."
      }
    },
    "john": {
        "headers": {
          "response_code": 404
        },
        "data": {
          "...": "..."
        }
    },
    "...": "..."
}

POST /batch

Post an object/map (top-level) with the following schema:

Property	Description	Example
Note: KEY	Any arbitrary string you want to use to identify the request.	req_1, department_info, foobar, 12
KEY.url	The API endpoint you want to call. You can also specify query-string params here.	/api/v2/me, /api/v2/tickets?page=2
KEY.method	(optional) GET, POST, DELETE, PUT. Defaults to GET.	GET
KEY.payload	(optional) When using POST/PUT, this is the JSON object you want to submit as the payload itself.	{"foo": "bar"}

GET /batch -- Short GET Syntax

You can also use the short GET syntax to process multiple GET requests all at once by specifying multiple get[KEY]=endpoint_path parameters.

Param	Description	Example
Note: KEY	The 'key' in get[KEY] can be any arbitrary string. It serves the same purpose as KEY above in the POST version of batch.
get[KEY]	The API endpoint to fetch	/api/v2/me, /api/v2/tickets

If you need to specify parameters for any of the get[KEY] calls (for example, to specify a page number), you can use the extended syntax.

Example GET call (note: for purposes of readability, the URL has been split on multiple lines):

curl -H "Authorization: key 1:CVRRGQ58QDX8H5B4W4RAJ978Q" \
    http://example.com/api/v2/batch/api/v2/batch?
        get[stars]=/api/v2/ticket_stars
        &get[departments]=/api/v2/ticket_departments

Here's an example where the endpoint contains parameters. You need to encode '?' and '&' so they don't get read by the main batch request itself.

curl -H "Authorization: key 1:CVRRGQ58QDX8H5B4W4RAJ978Q" \
    http://example.com/api/v2/batch/api/v2/batch?
        get[stars]=/api/v2/ticket_stars
        &get[tickets]=/api/v2/tickets%3Fpage%3D2%26ids%3D1%2C2%2C3%2C4

# the last line decodes to a URL like:
# /api/v2/tickets?page=2&ids=1,2,3,4