REST — Batch

Use the Batch REST endpoint to group together multiple sequential calls into a single network request. For environments which make a number of programmatic alterations to the session configuration, Batch can significantly reduce the network load and time to create the session.

In v2019.1+, The session ID can be passed as a URL parameter just as it is for the other REST endpoints.

In pre-2019.1Batch REST works a little differently than the rest of the REST endpoints. In particular, the Batch endpoint does not accept a Session ID URL parameter. This means that the first call in every batch request must be to POST /Sessions, to create a new session. Batch requests cannot operate on preexisting REST sessions—they must always create a new one. However, once you retrieve the session ID from a batch response, you can make normal, non-batch requests to that session.

When supplied as part of a Batch call, the individual requests are evaluated sequentially in the order they are supplied.

The GET|PATCH|DELETE /Sessions/{sid} endpoints are not supported by Batch REST.

Batch JSON

The body of a Batch call is formatted as an array of Batch objects, each of which has the following JSON format:

Name	Type	Writable	Description
Url	string	required	REST endpoint URL (for example the part following `/rest/`). Unlike standalone calls, the service names are case-sensitive in the Batch endpoint. Reference the service names from this list: REST — Data Sources REST — Data Objects REST — Data Objects REST — Folders REST — Functions REST — Data Joins REST — Parameters REST — Folders REST — Role Security REST — SchedulesV2 REST — Server Events REST — Sessions REST — Config Settings REST — Storage Management
Method	constant	required	Request method, one of: POST, PATCH, GET, DELETE The `GET\|PATCH\|DELETE /Sessions/{sid}` endpoints are not supported by Batch REST.
Payload	Payload	yes	Optional payload for POST and PATCH calls.

Example

[
  {
    "Url": "Sessions",
    "Method": "POST"
  },
  {
    "Url": "Roles/MyRole",
    "Method": "PATCH",
    "Payload": { ... }
  }
]

Payload JSON

The format of the Payload property depends on the Url, and mirrors the payload supplied for the non-batch versions of the endpoint. For example, when the Url is Parameters, the payload has the following format (as detailed in REST — Parameters):

{
  "Id":         "MyParameter",
  "DataType":   "String",
  "Value":      "",
  "PromptText": "Input a value",
  "IsHidden":   true
}

When the Url is Sessions/Save, only the FileName property in the payload is required. The current session ID will be used automatically.
For example:
{
    "Url": "Sessions/Save",
    "Method": "POST",
    "Payload": {
        "FileName" : "MyConfig.xml"
     }
  }

Making Batch Calls

POST /rest/batch

All Batch calls are made using the POST method. There is no session ID parameter (pre-v2018.2). Otherwise, calls to the Batch endpoint require the same Headers as all other REST calls. Each request object is supplied in order of evaluation. The response object contains the responses from each request in the same order that they were sent.

Adding additional Data Source column metadata or performing a GET for the Data Source Fields will result in fixing the current column metadata list as the only defined columns. The column metadata can be further altered, but will not be reflected in the Entity Columns collection until the session is launched in a browser.

Available parameters

Name Type Description

config

string

Specify which config file to create the session with.

Format: CustomConfigFile

All config files must use the same Temp path. Otherwise, you may experience errors when loading sessions.

Response JSON

Name	Type	Description
ReturnCode	string	Response code indicating whether the call was successful
ResponseContent	object	If the response code is 200 or 201, this is the content of the response. Otherwise this indicates whether an error occurred and the error type.

ResponseContent JSON

ReturnCode: 204

Name	Type	Description
StatusCode	int	Status code
StatusDescription	string	Status description

ReturnCode: 400-500

Name	Type	Description
reason	string	Error message
stacktrace	string	Stack trace, if available

Using curl

curl http://{webservice}/rest/batch -X POST ^
	-d "[{'Url':'Sessions','Method':'POST'}, ^
             {'Url':'Roles/Example','Method':'PATCH','Payload':{'IsActive':true}}]"

Example response

[
  {
    "ReturnCode": "201",
    "ResponseContent": {
      "AppUrl": "ExagoHome.aspx?...",
      "ApiKey": "...",
      "Id": "...",
      "Page": "ExagoHome",
      "ApiAction": "Default",
      "ExportType": null,
      "ShowTabs": true,
      "ShowErrorDetail": true,
      "ReportSettings": {
        "Id": null,
        "ReportPath": null,
        "SortsResource": null,
        "FilterItems": null,
        "IsError": false,
        "ErrorList": null
      }
    }
  },
  {
    "ReturnCode": "204",
    "ResponseContent": {
      "StatusCode": 204,
      "StatusDescription": null
    }
  }
]

Additional Resources

Admin Support Lab — Batch REST (video)