This part describes how to use the REST API bindings to interface with MATRIXX Engine.
The extended REST service APIs are implemented only in the RS Gateway. These APIs include REST services that manage subscribers, groups, and devices, including rehoming operations. In addition, you can start and stop rating sessions using the service APIs. Unlike the APIs described in MATRIXX Subscriber Management API, these APIs do not have a Python or Java equivalent. For information about the service API default filters, see the discussion about REST filters.
The Service APIs listed here are deprecated.
MATRIXX Subscriber Management API provides information about the MATRIXX Engine APIs, including functions, syntax, and result codes, and the MATRIXX Engine REST and Java API implementations.
The following information is an overview of the SubMan APIs and architecture.
The following sections introduce how the various in-memory objects are managed.
The SubMan API reference includes SubMan API and MDC descriptions.
RS Gateway supports the REST API bindings for accessing subscriber data in MATRIXX Engine. RS Gateway consists of an rsgateway application and a set of REST APIs.
The following APIs are deprecated in this release of MATRIXX and support for these APIs will be removed in a future release.
The balance management APIs include the messaging required to operate on a balance, meter, or wallet object. The primitives include the messaging and data elements required to create, modify, associate, and query objects directly related to a balance or meter, including their thresholds.
The catalog APIs return information about pricing catalogs for specified devices, groups, and subscriptions. They return catalog items that the specified object is eligible to purchase.
Use the following MDCs to import data for users, subscriptions, groups, and devices and to import catalog item purchase information for a subscription.
The device management APIs include the methods and functions required to operate on the device primary object. They include the data elements required to create, modify, and query devices, to add and remove a device from a subscription, and to delete a device from the Subscriber database.
This section describes the APIs for querying catalog items based on eligibility. The APIs return catalog items that the specified object is eligible to purchase.
The event APIs include the messaging and elements to return events and notifications in the Event Repository and the event database for subscriptions, groups, and users.
External payment APIs query external payment requests and get a list of external payment request records in a wallet.
The group management APIs include the messaging required to operate on the group object. The APIs include the messaging and data elements required to create, modify, associate, and query objects directly related to the group.
The multi-tenant APIs get tenant information for individual tenants and all tenants.
My MATRIXX supports GET, PUT, and POST REST bindings. The { } notation around text represents a URL parameter.
{ }
Use these APIs to query a list of status life cycles for an offer. You can query specific offer status life cycle using the profile ID.
The integration layer REST APIs manage payment authorization tokens for the payment gateway from the integration layer. These tokens are necessary for the client to communicate directly with the payment gateway to create a payment method in the payment gateway.
The policy APIs allow you to query the Sy policy counters for a specific device.
The pricing management APIs return information about all aspects of pricing, including catalog items, balance templates, product offers, billing cycles, life cycles, notifications and so forth. You can also get status information for the currently-loaded pricing.
The product offer management APIs include the messaging to activate, purchase, cancel, and modify catalog items. You can identify a product offer by its object ID or the external ID assigned during pricing plan creation.
Use the purchase package APIs to manage catalog items in a purchase package, including adding and removing catalog items for subscriptions, groups, and devices, and suspending, resuming, and canceling purchase packages.
The MtxRequestSubscriberEstimateRecurringCharge SubMan API estimates balance impacts from recurring processing of currently failing recurring cycles and upcoming recurring cycles (active purchased items cycles, balance cycles and billing cycles).
The rehoming APIs move a subscription, group, device, or user from one customer sub-domain to a different sub-domain. For a description of the rehoming process, see the discussion about rehoming subscribers, groups, devices, and users in the object management overview.
This service returns the administrators of a group. querySize=xx: An optional request parameter querySize (default is 10) can be specified that determines the number of records returned per call. queryCursor=yy: If the query results do not fit in a single response, a QueryCursor is included in the response. If the cursor is NULL or 0 you are at the end. You can retrieve the subsequent pages of a response by calling this URL again but specifying a queryCursor parameter on the url.
This extended subscriber query service returns complete details about the subscriber including their wallet and detailed information about the subscriber.
This service implements the retrieval of the groups for which this subscriber is the administrator. querySize=xx: An optional request parameter querySize (default is 0=system default) can be specified that determines the number of records returned per call. queryCursor=yy: If the query results do not fit in a single response, a QueryCursor is included in the response. If the cursor is NULL or 0 you are at the end. You can retrieve the subsequent pages of a response by calling this URL again but specifying a queryCursor parameter on the url.
This service creates a device and a subscriber and associates them both together.
This service modifies subscriber authentication data. RS Gateway encodes the password before saving it in the database. Because the main purpose of this method is to encode the password, the password is required.
This method is used to check if auth data matches with the one saved in the engine. This service will take in Password as required and LoginId as optional. If both are provided both have to match. If only Password is provided only password has to match. Return value will be the AuthData object (including Roles) of that subscriber. This service will work off the encoded password so the passed in value will be encoded before we compare it with the stored value.
This service modifies a subscriber's password. You must pass in the old password value to check whether it is a match with existing password in the database, before setting the new password. The method will handle the compare and persistence using the defined password encoder.
This custom device query method provides enhanced details about a device.
This service simulates usage.
This service starts a rating service.
This service stops a rating request that was initiated by the start rating service.
This service gets update info of the rating request that was initiated by the start rating service.
Custom group query service. This rest call provides an extended group query service which includes detail information about the wallet.
This service implements an add to a group taking a document with arrays of query terms.
This service searches for virtual balances tied to the group balance. You provide the group and the ResourceId for the parent balance. The API will look at members and subgroups of the group and return the top used balances tied to the parent balance. The API will return a partial set of information if there are more than one page of members or subgroups in the group. You can specify a single querySize that will be used to determine how many members and subgroups will be returned. A cursor from a previous query can be specified to continue retrieval.
This service implements a remove from a group taking a document with arrays of query terms.
This service returns the sub groups of a given group. querySize=xx: An optional request parameter querySize (default is 0=system default) can be specified that determines the number of records returned per call. queryCursor=yy: If the query results do not fit in a single response, a QueryCursor is included in the response. If the cursor is NULL or 0 you are at the end. You can retrieve the subsequent pages of a response by calling this URL again but specifying a queryCursor parameter on the url.
This service returns the subscribers that are direct members of the group. querySize=xx: An optional request parameter querySize (default is 0 which means use the system default) can be specified that determines the number of records returned per call. queryCursor=yy: If the query results do not fit in a single response, a QueryCursor is included in the response. If the cursor is NULL or 0 you are at the end. You can retrieve the subsequent pages of a response by calling this URL again but specifying a queryCursor parameter on the url.
This service collects composite data for the specified group.
This service searches for entity objects in the MATRIXX realtime object database. Allowable search criteria for subscribers, groups, subscriptions, users and/or devices can be specified. The response is the embellished response objects provided via the extended services of the RS Gateway.
Custom query method provides list of configured subdomains.
This service creates a device and a subscription and associate them both together.
This extended subscription query service returns complete details about the subscription including the wallet and detailed information about the subscription.
This service creates a device that is associated with the subscriber. Will read an MtxRequestDeviceCreate message from post data and submit it to the engine.
This service removes a device from a subscriber object and then deletes it.
This service creates a device to associate with the existing subscriber. Will also purchase any offers passed in for the subscriber.
This service implements the retrieval of the groups to which this subscriber belongs. querySize=xx: An optional request parameter querySize (default is 0=system default) can be specified that determines the number of records returned per call. queryCursor=yy: If the query results do not fit in a single response, a QueryCursor is included in the response. If the cursor is NULL or 0 you are at the end. You can retrieve the subsequent pages of a response by calling this URL again but specifying a queryCursor parameter on the url.
This service collects composite data for specified subscription.
Remove a subscription from a user object and then delete it
This service creates a user, subscription, device and associates them all together. You can also buy subscription offers in this call. Note that you cannot buy device-level offers using this call; only subscription-level offers.
This service creates a subscription that is associated with the user. It reads an MtxRequestSubscriptionCreateBasic message from post data and submits it to the engine.
Modify a user and auth data
This service modifies user authentication data. RS Gateway encodes the password before saving it in the database. Because the main purpose of this method is to encode the password, the password is required.
This service checks if user data matches with the one saved in the engine. This service will take in Password as required and LoginId as optional. If both are provided both have to match. If only Password is provided only password has to match. Return value will be the AuthData object (including Roles) of that subscriber. This service will work off the encoded password so the passed in value will be encoded before we compare it with the stored value.
This service modifies a user's password. You must pass in the old password value to check whether it is a match with existing password in the database, before setting the new password. The method will handle the compare and persistence using the defined password encoder.
Use these APIs to query status life cycle information for devices, groups, subscriptions, and users from the engine.
The status modify APIs schedule status changes and delete scheduled status changes. They also suspend and resume purchased items (product offer or bundle) if the current offer status class permits the action.
The Subscriber REST APIs described here are deprecated and will be removed in a future release.
The subscription management APIs include the messaging required to operate on the subscriber object, which is a primary object for MATRIXX interactions. The API bindings include the messaging and data elements required to create, modify, and query objects directly related to the subscription. A subscription must have a wallet secondary object, which is created for the subscription at subscription creation time.
The system REST APIs query the MATRIXX Engine to check if recurring recharge is enabled, return domain and sub-domain information, return tenant IDs, and create Pay Now client tokens.
The tax APIs manage information in the US Tax database.
Use the User REST APIs to add, update, query, and delete users. You can also get and modify user authentication data, associate users with groups and subscriptions, and modify or remove those associations.
This part provides an overview of how to use the Java™ API binding for the SubMan v3 API as an interface to the MATRIXX Engine.
