REST URL and Method Format

MATRIXX uses the standard REST URL and method formats.

The format for the XML URL is:

http://host:port/rsgateway/data/v3/object/object_identifier/object?parameter&parameter

The format for the JSON URL is:

http://host:port/rsgateway/data/json/object/object_identifier/object?parameter&parameter

The format for the OpenAPI URL is:

http://host:port/rsgateway/data/openapi/object/object_identifier/object?parameter&parameter

The host and port are defined by your installation configuration. There is no authentication or authorization enforced. The calling program is responsible for authentication and authorization before passing a call to the RS Gateway.

For a primary object (such as a device, subscriber, or group) in a URL, which is located after the v3/, json, or openapi identifier, the Object ID is required.

Optional parameters are preceded by ? and separated by &. All REST calls take an optional HTTP parameter, ApiEventData=XXX, where XXX is either a JSON string or XML string encoded in URL format. These strings should be JSON or XML serialized data containers. If present, the strings are used to populate the ApiEventData field of the base MtxRequest object. For example:

<MtxRequestSubscriberAddDevice>
  <ApiEventData>
    <CustomApiEventDataExtension>
      <StringField>Subscriber Add Device</StringField>
      <Int32Field>2468</Int32Field>
    </CustomApiEventDataExtension>
  </ApiEventData>
</MtxRequestSubscriberAddDevice>

For calls that include a {SearchTerm}, the default search term is the ObjectId. To specify a different search term, such as an access number, include the term and its value separated by a + character. For example, to top-up a subscriber balance using the AccessNumber as the search term, issue the call using this format:

PUT http://host:port/rsgateway/data/v3/subscriber/AccessNumber+5555555555/wallet/12/topup

For more information about search terms see the discussion about REST operation search terms.

The following is an example of a typical call to purchase an offer for a device using XML. In this example, the optional parameter executeMode specifies that the call is executed in advice mode (credit limits of actual currency balances are ignored, events are not generated, the database is not updated, and notifications are not sent). For more information about advice mode, see the discussion about execute mode.

PUT http://localhost:8080/rsgateway/data/v3/device/0-1-5-7/offers?executeMode=2

POST and PUT calls typically require the caller to provide both the URL and a body. The following example illustrates the XML body of data for this PUT call.

<MtxRequestDevicePurchaseOffer>
    <OfferRequestArray>
        <MtxPurchasedOfferData>
            <ProductOfferId>415</ProductOfferId>
            <StartTime>2017-06-01T00:00:00</StartTime>  
            <EndTime>2017-07-31T00:00:00</EndTime>
        </MtxPurchasedOfferData>
    </OfferRequestArray>
</MtxRequestDevicePurchaseOffer>

Here is the same call using JSON.

PUT http://localhost:8080/rsgateway/data/json/device/0-1-5-7/offers?executeMode=2

The following example illustrates the JSON body of data for this PUT call.

{
    "$": "MtxRequestDevicePurchaseOffer",
    "OfferRequestArray": [
      {
        "$": "MtxPurchasedOfferData",
           "ProductOfferId": 415,
           "StartTime": 2017-06-01T00:00:00,
           "EndTime": 2017-07-01T00:00:00
       }
     ]
}

The timestamp format is yyyy-MM-ddTHH:mm:ss[.ffffffZ]

yyyy-MM-dd — year-month-day
T — separates the date and time
HH:mm:ss — hour:minute:seconds
[.ffffffZ] — optional milliseconds and the letter Z as a zone designator for zero offset
Note: To specify an offset, use the format yyyy-MM-ddTHH:mm:ss[.ffffff][+|-|Z][HH:mm]

The assignment of optional field values depends on whether the call creates an object with that field or whether it modifies an object.

For calls that create objects, the value for unpopulated optional fields is NotPresent (set to NULL).
For calls that modify objects, the value for unpopulated optional fields remains set to the current value.