Making Multiple Requests in One API Call

You can perform multiple engine requests (MtxRequestMulti) using a POST call to the RS Gateway. For example, one request can create a subscriber, create a device, and associate the device with that subscriber.

Unlike the RS Gateway REST services, the POST of an MtxRequestMulti operation can be semantically any type of operation (READ, UPDATE, CREATE, or DELETE).
Note: The REST services use GET, PUT, POST, DELETE request methods and the URL and payload to semantically map to the READ, UPDATE, CREATE and DELETE types respectively.
Please note the following MtxRequestMulti POST call restrictions:
  • The POST of MtxRequestMulti does not go through the REST processing pipeline of operations, so there is no mechanism to transform or filter the requests or the responses for these operations.
  • Subscriber management operations that interact with the Payment Service to manage payment methods cannot be used within a MtxRequestMulti call. This includes the following APIs:
    • AddPaymentMethod
    • ModifyPaymentMethod
    • DeletePaymentMethod
    • SysCreateClientToken
Important: To implement multiple operations in a single call and also support the standard REST processing pipeline of filters and transformers, you must create new REST services using the Business API SDK. These new services are written and deployed inside the RS Gateway.

To implement a multi-request call, create a MtxRequestMulti SubMan operation and inside it, create a MtxRequest for each operation to perform. For example, include MtxRequestSubscriberCreate, MtxRequestSubscriberAddDevice, and MtxRequestSubscriberPurchaseOffer in one request. The <MultiRequestIndex> identifies the object in a request operation. Each request increments the index value by 1 with the first index value=0.

Important: When making multiple sub-requests in one SubMan API call, the value of the ExecuteMode field in the top level MtxRequestMulti field determines the execution mode for every sub-request. Every sub-request will have the same execution mode. The ExecuteMode field in the nested sub-request is not used. For more information about the ExecuteMode field, see the discussion about execution mode.

The MtxRequestMulti API has a corresponding MtxResponse that contains an array of MtxResponse messages — one for each MtxRequest operation defined in the MtxRequestMulti call. If a request fails on an object because there is a duplicate index key/value found in the Transaction Server (error code 19), the response message includes information about the object. For example, MtxSubscriberObject.ExternalId=100001 for 0:1:5:19.

A multi-request call is sent to the engine using a POST request: 
POST http://host:port/rsgateway/data/v3

For more information about making multi-request calls, see the call-specific API documentation.

Example Multi-Request Message

The following code shows an example multi-request message. Notice that the index value of the create subscriber request (0 because it was the first call) and the index value of the create device request (1 because it was the second call) are used to add the device to the subscriber in one transaction. The XYZCompanyDeviceExtension is a custom extension derived from a mobile device and it has all the mobile device fields in addition to its own custom fields. 
<MtxRequestMulti>
  <RequestList>
    <MtxRequestSubscriberCreate>
      <ExternalId>Employee1</ExternalId>
      <FirstName>Subscriber</FirstName>
      <LastName>Employee1</LastName>
      <ContactEmail>[email protected]</ContactEmail>
      <ContactPhoneNumber>1234567890</ContactPhoneNumber>
      <NotificationPreference>0</NotificationPreference>
      <TimeZone>Europe/London</TimeZone>
      <BillingCycle>
        <MtxBillingCycleData>
          <BillingCycleId>414</BillingCycleId>
          <DateOffset>4</DateOffset>
        </MtxBillingCycleData>
      </BillingCycle>
      <Attr>
        <TrainingSubscriberObjectExtension>
          <CustomerSegment>group</CustomerSegment>
        </TrainingSubscriberObjectExtension>
      </Attr>
    </MtxRequestSubscriberCreate>
    <MtxRequestDeviceCreate>
      <ExternalId>1234567890</ExternalId>
      <DeviceType>0</DeviceType>
      <Attr>
        <TrainingDeviceObjectExtension>
          <TAC_Code>PM123</TAC_Code>
          <Imsi>1234567890</Imsi>
          <AccessNumberArray>
            <value>1234567890</value>
          </AccessNumberArray>
        </TrainingDeviceObjectExtension>
      </Attr>
    </MtxRequestDeviceCreate>
    <MtxRequestSubscriberAddDevice>
      <SubscriberSearchData>
        <MtxSubscriberSearchData>
          <MultiRequestIndex>0</MultiRequestIndex>
        </MtxSubscriberSearchData>
      </SubscriberSearchData>
      <DeviceSearchData>
        <MtxDeviceSearchData>
          <MultiRequestIndex>1</MultiRequestIndex>
        </MtxDeviceSearchData>
      </DeviceSearchData>
    </MtxRequestSubscriberAddDevice>
  </RequestList>
</MtxRequestMulti>

For information about creating a multi-request service, see the discussion about creating multi-request REST services in MATRIXX Business API SDK.

Sample Java Program

MATRIXX provides a sample Java program that implements a multi-request call (com/matrixx/test/MultiRequestTest.java). For more information about the sample Java program, see the discussion about creating a java client application.

Multi-Request Rules for Tenancy

When making multi-requests that affect tenancy, the following actions are taken:
  • When modifying a device, the subscriber's tenancy is checked to ensure consistency.
  • When adding a device or modifying a subscriber, the subscriber's devices and subscriber's user (owner) tenancy are checked to ensure consistency.
  • When adding a device or modifying a subscription, the subscription's devices and subscriber's user (owner) tenancy are checked to ensure consistency.
  • When modifying a group, the group's user (owner) tenancy is checked to ensure consistency.
  • When modifying a user, adding a subscription or modifying a subscription, adding a group or modifying a group, the tenancy is checked to ensure consistency.