Batch requests

From a system API perspective, a batch request is a set of requests that are executed in a non-transactional sequence. Each call within the batch request is referred to as a subrequest. The object that contains all of the subrequests is referred to as the main request.

Subrequests are executed serially, in the order they are specified in the request payload. PolicyCenter then gathers the response to each subrequest and returns them in a single response payload. Once again, the subresponses appear in the same order as the corresponding subrequests.

When the response to a batch request contains a response code of 200, it means the batch request itself was well-formed. However, each individual subrequest may have succeeded or failed.

Batch requests are limited to a maximum number of subrequests. The maximum is specified by the MaximumAllowedNumberOfBatchSubRequests configuration parameter. In the base configuration, this parameter is set to 100. Batch requests with more than the maximum number of subrequests fail with a BadInputException.

Batch requests are limited to a maximum number of subrequests. For more information, see Configuring the maximum number of subrequests.

Optional subrequest attributes

A subrequest can optionally have query parameters that refine the corresponding subresponse payload.

By default, each subrequest inherits the information in the headers of the main request object. The one exception to this is the GW-Checksum header. This header is not inherited because it is unlikely that a single checksum value will correspond to multiple sub-requests. You can optionally specify header values for an individual subrequest, which will override the corresponding values in the main request header.

If a subrequest fails, the default is to continue processing the remaining subrequests. For each subrequest, you can optionally specify that if the subrequest fails, PolicyCenter must skip the remaining subrequests.

For a complete list of options and further information on how they work, refer to the batch_pl-1.0.schema.json file.

Batch request syntax

Batch request call syntax

The syntax for the batch request call is:

POST <applicationURL>/rest/<apiWithVersion>/batch

For example, if you were executing a Policy API batch from an instance of PolicyCenter on your local machine, the call would be:

POST http://localhost:8180/pc/rest/policy/v1/batch

Batch request payload syntax

The basic syntax for a batch request payload is:

{
  "requests": [
    {
      "method": "<method>",
      "path": "<path>",
      "query": "<queryParameters>",
      "data":
        {
          "attributes": {
            "<field1>": "<value1>",
            "<field2>": "<value2>",
            ...
          }
        }
    },
    {
      "method": "<method>",
      "path": "<path>",
      "query": "<queryParameters>",
      "data":
        {
          "attributes": {
            "<field1>": "<value1>",
            "<field2>": "<value2>",
            ...
          }
        }
    },
    ...
  ]
}

where:

<method> is the operation in lower case, such as "get", "post", "patch", or "delete".
<path> is the endpoint path.
- This path starts as if it was immediately following the API path (including the major version, such as "/v1"). For example, suppose the path for a command when executed in isolation is: http://localhost:8180/pc/rest/policy/v1/policies/cc:22/activities/cc:55. The path within a batch is: /policies/cc:22/activities/cc:55
<queryParmaters> is an optional string of query parameters. Start this string without an initial "?".
<field1/<value> are the field and value pairs of the request body.

The following sections provide examples of how to use this syntax.

Simple batch requests

The most simple batch request consist of default GET subrequests. This involves no query parameters and no request payloads.

For this example, the response will consist of three subresponses. Each subresponse will consist of the default fields for each policy.

{
  "requests": [
    {
      "method": "get",
      "path": "/policies/demo_sample:1"
    },
    {
      "method": "get",
      "path": "/policies/demo_sample:2"
    },
    {
      "method": "get",
      "path": "/policies/demo_sample:3"
    }
  ]
}

Batch requests with query parameters

The following is an example of a batch request with multiple GET subrequests. This example includes query parameters for some of the GETs. As shown in the example, it is possible for some subrequests to use query parameters while others do not. The subrequests that use query parameters can use different query parameters.

The response will consist of three subresponses. The fields in each subresponse will vary based on the query parameters.

{
  "requests": [
    {
      "method": "get",
      "path": "/policies/demo_sample:1",
      "query": "sort=createdDate"
    },
    {
      "method": "get",
      "path": "/policies/demo_sample:2",
      "query": "fields=*all"
    },
    {
      "method": "get",
      "path": "/policies/demo_sample:3"
    }
  ]
}

Batch requests with request payloads

The following is an example of a batch request with multiple POST subrequests. This example includes request payloads for each subrequest.

In this example, two notes are POSTed to different activities. But it would also be possible to POST each note to the same activity.

{
  "requests": [
    {
      "method": "post",
      "path": "/activities/xc:11/notes",
      "data":
        {
          "attributes": {
            "body": "Batch note 1"
          }
        }
    },
    {
      "method": "post",
      "path": "/activities/xc:73/notes",
      "data":
        {
          "attributes": {
            "body": "Batch note 2"
          }
        }      
    }
  ]
}

Batch requests with distinct operations

Every subrequest in a batch request is distinct from the other subrequests. There is no requirement for any subrequest to share any attribute with any other subrequest. Thus, the following is an example of a batch request with multiple subrequests where each subrequest uses a different operation.

{
  "requests": [
    {
      "method": "post",
      "path": "/activities/xc:21/notes"
      "body": {
        "data": {
          "attributes": {
            "body": "Batch activity 1",
            "subject": "Batch activity 1",
            "topic": {
              "code": "general",
              "name": "General"
            }
          }
        }
      }
    },
    {
      "method": "patch",
      "path": "/notes/xc:22",
      "body": {
        "data": {
          "attributes": {
            "body": "PATCHed note body"
          }
        }
      },
    },
    {
      "method": "delete",
      "path": "/notes/xc:23"
    },
    {
      "method": "get",
      "path": "/activities/xc:24/notes",
      "query": "sort=subject&fields=id,subject"
    }
  ]
}

Specifying subrequest headers

The following is an example of a batch request where each subrequest has a header that overrides the main request header.

{
  "requests": [
    {
      "method": "delete",
      "path": "/activities/xc:55",
      "headers": [
        {
          "name": "GW-Checksum",
          "value": "2"
        }
      ]
    },
    {
      "method": "delete",
      "path": "/activities/xc:57",
      "headers": [
        {
          "name": "GW-Checksum",
          "value": "4"
        }
      ]
    }
  ]
}

Specifying onFail behavior

The following is an example of a batch request that uses onFail to specify that if any of the subrequests fail, the remaining subrequests need to be skipped.

{
  "requests": [
    {
      "method": "patch",
      "path": "/activities/xc:93",
      "body": {
        "data": {
          "attributes": {
            "subject": "PATCH body 1"
          }
        }
      },
      "onFail": "abort"
    },
    {
      "method": "patch",
      "path": "/activities/xc:94",
      "body": {
        "data": {
          "attributes": {
            "subject": "PATCH body 2"
          }
        }
      },
      "onFail": "abort"
    },
    {
      "method": "patch",
      "path": "/activities/xc:95",
      "body": {
        "data": {
          "attributes": {
            "subject": "PATCH body 3"
          }
        }
      }
    }
  ]
}

Configuring the maximum number of subrequests

The greater the number of subrequests in a batch request, the greater the chances that there will be a compromise in performance. A batch request with the maximum number of subrequests could result in a slow response, depending on what the maximum is and what those subrequests are doing.

In the base configuration, the maximum number of subrequests is 100. This can be raised to a greater value. However, batch requests with a significantly large number of subrequests could have negative consequences, such as:

The request consuming a significant amount of service resources. This could include both memory and database resources.
The request taking so long to complete that it times out before a response can be provided to the caller.

Consequently, Guidewire recommends setting the maximum number of subrequests to the lowest value that is needed. If there is a legitimate business need to raise the maximum above 100, Guidewire recommends the limit be raised only as much as is absolutely necessary.

Also, be aware that batch requests are subject to any application server limitations around the maximum size of a request body. Thus, it is possible for a batch request to be too large to process, even if the number of subrequests is at or below the allowed maximum.