responses

Once a batch request is executed, it returns a list of BatchResponses. The responses correspond to the retrieve requests and changesets in the same order that they were passed to the batch function. Requests that were not successful are reflected as ErrorResponses. Responses to successful requests are represented as ReadResponses for retrieve requests, and WriteResponses for changesets.

To determine if a request was successful use .isSuccess(). Then, depending on the corresponding request, you can parse the response or handle the error.

ReadResponse

Successful retrieve requests can be cast to ReadResponse, which contains the HTTP code, the raw body, and the constructor of the entity that was parsed from the response. To work with an instance of the retrieved entity, you can use the .as method, which allows you to transform the raw data into an instance of the given constructor. Note, that the .as method transforms the raw data to an array of entities, even if the original request was a GetByKeyRequestBuilder. Also note, that retrieve responses can be ErrorResponses. Therefore, it is crucial to check responses for success, before casting them to ReadResponse.

In the example below, we combine a list of GetByKeyRequestBuilders into one batch request and execute it against a destination. If one of the requests was unsuccessful, an error will be thrown. Otherwise, the responses are transformed into instances of BusinessPartnerAddress.

async function getAddressesByIds(
  ...retrieveRequests: GetByKeyRequestBuilder<BusinessPartnerAddress>[]
): Promise<BusinessPartnerAddress[]> {
  // Execute batch request combining multiple retrieve requests
  const batchResponses = await batch(...retrieveRequests).execute(destination);

  // Error handling
  if (batchResponses.some(response => !response.isSuccess())) {
    throw new Error('Some of the batch subrequests were not successful.');
  }

  return batchResponses.reduce(
    (addresses: BusinessPartnerAddress[], response: BatchResponse) => [
      ...addresses,
      // Transform response to an instance of BusinessPartnerAddress
      ...(response as ReadResponse).as(BusinessPartnerAddress)
    ],
    []
  );
}

WriteResponses

Successful changeset requests can be cast to WriteResponses which contains all subresponses for the changeset request. Those responses can be accessed by .responses and have the type WriteResponse. Each WriteResponse contains the HTTP code and can contain the raw body and the constructor of the entity that was parsed from the response, depending on whether there was a body in the response. Create and delete requests typically do not have a response body. To work with an instance of an entity given in a WriteResponse, you can use the .as method, which allows you to transform the raw string body into an instance of the given constructor. Note that the response may not exist, so you should only call this method if you know that there is data. Typically the HTTP code is a good indicator for this - 201 No Content probably won't have content. If you are working with TypeScript you will have to tell the compiler, that the .as! method can be used here by adding a !. Also note, that the response to a changeset can be an ErrorResponse. Therefore, it is crucial to check responses for success, before casting them to WriteResponses.

In the example below, we combine a list of UpdateRequestBuilders into one changeset and pass it to the batch request, which we execute against a destination.

Once we execute the batch request, we get a list of BatchResponses, which contains one response only.

If the request was unsuccessful, an error will be thrown. Otherwise, the subresponses are transformed into instances of BusinessPartnerAddress.

async function updateAddresses(
  ...updateRequests: UpdateRequestBuilder<BusinessPartnerAddress>
): Promise<BusinessPartnerAddress[]> {
  // Execute batch request with one changeset
  const batchResponses = await batch(
    // Combine update requests into one changeset
    changeset(...updateRequests)
  ).execute(destination);

  // Get response for the changeset request
  const changesetResponse = batchResponses[0];

  // Error handling
  if (!changesetResponse.isSuccess()) {
    throw new Error('The changeset request was not successful.');
  }

  return changesetResponse.responses.map(response =>
    // Transform response to an instance of BusinessPartnerAddress
    response.as!(BusinessPartnerAddress)
  );
}

ErrorResponse

Unsuccessful retrieve requests and changesets are reflected as ErrorResponses in the response. Those responses have an httpCode (a number) and a body (a JSON object).