Administering composite requests

If any of the subrequests in the requests section fail, Cloud API does the following:

• Does not commit any of the data
• Does not execute any GETs in the selections section
• Returns a 400 error

Cloud API also returns a response.

• The response begins with the following: "requestFailed": true. This is to make it easy to identify that the composite request did not commit data.
• For the initial subrequests that did not fail (if any), the response is returned.
  • This is either the response as specified by the associated endpoint (and any query parameters), or the "responseIncluded": false text.
  • The standard response can be useful for debugging purposes, as you can see the state of objects that succeeded before the subrequest that failed.
• For the subrequest that failed, the error message is returned.
• For the subrequests after the failed subrequest, the text "skipped": true is returned.
• If a selections section was included, the text "skipped": true is returned for each subselection.

For example, the following is the response for a composite request with five subrequests and a set of queries. All subrequests have responseIncluded set to false. The third subrequest failed because the dueDate attribute was incorrectly spelled as ueDate.

{
  "requestFailed": true,
  "responses": [
    {
      "responseIncluded": false
    },
    {
      "responseIncluded": false
    },
    {
      "requestError": {
        "details": [
          {
            "message": "Schema definition 'ext.common.v1.common_ext-
                1.0#/definitions/Note' does not define any property
                named 'ueDate'",
            "properties": {
              "lineNumber": 1,
              "parameterLocation": "body",
              "parameterName": "body"
            }
          }
        ],
        "developerMessage": "The request parameters or body had issues. 
           See the details elements for exact details of the problems.",
        "errorCode": "gw.api.rest.exceptions.BadInputException",
        "status": 400,
        "userMessage": "The request parameters or body had issues"
      },
      "status": 400
    },
    {
      "skipped": true
    },
    {
      "skipped": true
    }
  ],
  "selections": [
    {
      "skipped": true
    }
  ]
}

If there is an error in the selections section only, the subrequests in the requests section will execute, the data will be committed, and the composite request will return with a 200 response code, indicating success. Cloud API also attempts to execute each subselection as best as possible.

Cloud API logs information about composite requests at both the composite request level and the subrequest/subselection level. This information appears in the logs under the CompositeSubRequest marker, which is a child of the normal RestRequest marker.

Each subrequest and subselection log message details information for that subrequest/subselection, such as the actual path, the HTTP method, and the apiFqn. The same log parameter names and conventions are used for both the parent request logging and the subrequest logging, such as whether a given value is logged with an empty string or whether it is omitted. However:

• Some parameters are always omitted at the subrequest level because they only make sense for the parent request.
• Some additional composite-specific parameters are added.

For example, suppose you executed the previous composite request example in which a composite request creates two notes for activity xc:202. The corresponding log entries could appear as follows. Note that the first message is for the parent request and the next two messages are for the two subrequests:

server-id-207          749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13 
14:40:30,803 INFO <RestService[ GW.PL ]> Operation started 
{path="/composite/v1/composite", from="[0:0:0:0:0:0:0:1]", method="POST", 
query="", startTime=1227026673066900, message="", eventType="START", 
serverID="server-id-207"}

server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13 
14:40:30,894 INFO <CompositeSubRequest[ RestRequest ]> Operation status 
{path="/common/v1/activities/xc:202/notes", query="", method="POST", 
pathTemplate="/common/v1/activities/{activityId}/notes", 
apiFqn="ext.common.v1.common_ext-1.0", status=201, error="", userMessage="", 
devMessage="", elapsedTimeMs=53, message="Composite API subrequest 
succeeded", eventType="STATUS", serverID="server-id-207"}

server-id-207 aapplegate 749bdc4c-34b9-4f63-9b54-d1b0442af2c5 2021-12-13 
14:40:30,899 INFO <CompositeSubRequest[ RestRequest ]> Operation status 
{path="/common/v1/activities/xc:202/notes", query="", method="POST", 
pathTemplate="/common/v1/activities/{activityId}/notes", 
apiFqn="ext.common.v1.common_ext-1.0", status=201, error="", userMessage="", 
devMessage="", elapsedTimeMs=4, message="Composite API subrequest 
succeeded", eventType="STATUS", serverID="server-id-207"}

Each subrequest or subselection always generates a log statement, whether the subrequest succeeded, failed, or was skipped due to prior failures. A separate log statement is also added specifically for the commit of the composite request, whether the composite request commit succeeded, failed, or was skipped.

Composite requests are limited to a maximum number of subrequests and subselections. The maximum is specified by the MaximumAllowedNumberOfCompositeSubRequests configuration parameter. In the base configuration, this parameter is set to 100. Composite requests with more than the maximum number fail with a BadInputException. (The maximum applies to the sum of the number of subrequests and the number of subselections.)

The greater the number of subrequests in a composite request, the greater the chances that there will be a compromise in performance. A composite 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.

You can increase the maximum number of subrequests to a value greater than 100. However, composite 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 composite requests are subject to any application server limitations around the maximum size of a request body. Thus, it is possible for a composite request to be too large to process, even if the number of subrequests is at or below the allowed maximum.