RS Gateway OpenAPI Swagger Documentation

You can request the complete RS Gateway JSON Swagger OpenAPI (data structure version 3.0.0) documentation.

Schema and Extension Versions

RS Gateway uses the latest MDC schema versions. When necessary, you can control the version of MDCs used when constructing requests to send to MATRIXX Engine and the information returned by RS Gateway by specifying the schema version and extension number in the REST call.

If you do not specify a schema version and extension number in the REST calls described here, RS Gateway defaults the schema fields to their highest known values. When you specify a version number, RS Gateway uses that version number for the entire request and response.

Important: Setting the schema version and extension number is optional. The OpenAPI calls can explicitly contain the schema number and extension number in the payload but it is not required. If the call does specify versions, it is the highest priority and takes precedence. Specifying the versions in the header is optional. The methods for setting the versions in order of precedence are:

Specify the schema and extension versions in the header:
- X-MATRIXX-SchemaNumber — This is the MATRIXX system version number and is always one of the MATRIXX release numbers.
- X-MATRIXX-ExtensionNumber — This is the customer-specific extension version.
The session schema (set in the request).

The following example shows how to set the schema version and extension version in the header of the call:

curl -v -H "X-MATRIXX-SchemaNumber: 5240" -H "X-MATRIXX-ExtensionNumber: 3" http://localhost:8080/rsgateway/data/json/openapi3/schema/{MdcName}

Note: If you use a schema or extension version number that does not exist, a 422 status code is returned indicating that the value is greater than the maximum allowable value. You should specify both the SchemaNumber and the ExtensionNumber or neither.

Request OpenAPI Swagger Documentation

To get the RS Gateway JSON OpenAPI Swagger documentation, use the following service:

GET rsgateway/data/json/openapi3

After issuing the GET call, the RS Gateway response includes information similar to the following:

 {
    "openapi": "3.0.0",
    "info": {
        "title": "Matrixx OpenAPI",
        "version": "1.0.0"
    },
    "servers": [
        {"url": "localhost:8080/rsgateway/data"}
    ],
    "tags": [
        {"name": "device"},
        {"name": "event"},
        {"name": "eventstore"},
        {"name": "gateway"},
        {"name": "group"},
        {"name": "login"},
        {"name": "pricing"},
        {"name": "service"},
        {"name": "stream_info"},
        {"name": "subscriber"},
        {"name": "subscription"},
        {"name": "system"},
        {"name": "task"},
        {"name": "user"}
    ],
    "components": {
        "schemas": {...
}

URLs in OpenApi3 documents use the URL of the running system including when the RS Gateway is accessed through a proxy server. You can overwrite the URLs using either of the following:

-Drsgateway.openapi_base_url=http://host:port/rsgateway/data
Set openapi_base_url: http://host:port/rsgateway/data in the /opt/mtx/conf/rsgateway-extensions.yaml file.

Filter Response by MDC Name

To get the RS Gateway JSON OpenAPI Swagger documentation for a specific MDC, use the following service:

GET rsgateway/data/json/openapi3/schema/{MdcName}

The MdcName is the name of an MDC.

Documentation refers to schemas by the full URL and referenced schemas include the full URL. Schemas include simple examples for objects and properties of objects. References to internal data structures are marked as "Internal Only." The date format in the OpenApi documentation is "9999-12-31T23:59:59.999999Z."

For example, GET /rsgateway/data/json/openapi3/schema/MtxResponseEvent returns:

{
  "description": "Response to an event query. (extends MtxResponse)",
  "examples": {
    "event": {
      "balanceStateUpdateArray": [
        {
          "appliedOfferIndex": 0,
          "balanceClassId": 0,
          "balanceDeviceId": "1-2-3-4",
          "balanceEndTime": "2020-02-03T04:05:06.789123-0800",
          "balanceResourceId": 0,
          "balanceTemplateId": 0,
          "endTimeExtensionLimitCount": 0,
          "endTimeExtensionLimitUnitType": 0,
          "mtx_container_name": "MtxBalanceStateUpdate",
          "mtx_ext_ver": 2,
          "mtx_sys_ver": 5240,
          "oldBalanceEndTime": "2020-02-03T04:05:06.789123-0800"
        }
      ],
   …
  },
  "properties": {
    "event": {
      "description": "The event.",
      "discriminator": {
        "propertyName": "mtx_container_name"
      },
      "example": {
         …
      },
      "oneOf": [
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/txNoGDataEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/PaymentAuthorizationEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxWriteOffEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxVoiceEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxUserModifyEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxUserEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxUserDeleteEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxUserCreateEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxUsageRefundEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxUsageEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxTransferToBilledAREvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSuspendEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSubscriptionModifyEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSubscriptionEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSubscriptionDeleteEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSubscriptionCreateEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSubscriberRemoveDeviceEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSubscriberAddDeviceEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxStatusChangeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSessionEndEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSessionContextEndEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxSecondaryEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxRolloverBalanceAdjustEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxResumeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxRefundEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxRecurringEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxRechargeRequestEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxRechargeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPurchasedItemTransitionToInactiveEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPurchasedItemStatusChangeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPurchasedItemModifyEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPurchasedItemCycleChangeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPurchasedItemActivationEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPurchaseEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPrimaryEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPolicyChangeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPeriodWriteOffEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPeriodTerminationEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPeriodEndTimeChangeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPaymentSettlementEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPaymentRefundEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPaymentEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxPaymentAuthorizationEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxObjectDeleteEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxObjectCreateEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxNotificationEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxNotificationDoneEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxMissedContractChargeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxMeterPeriodCloseEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxGroupRemoveMembershipEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxGroupModifyEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxGroupEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxGroupDeleteEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxGroupCreateEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxGroupAddMembershipEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxForfeitureEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxFirstUsageEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxFinanceContractPrincipalPaymentEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxFeeChargeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxExternalPaymentRequestEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxExternalPaymentEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxDeviceModifyEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxDeviceEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxDeviceDeleteEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxDeviceCreateEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxDebtPaymentEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxDataEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxContractLateChargeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxContractFinanceEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxContractDebtPaymentEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxComponentMeterPeriodCloseEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxCancelEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxBillingCycleChangeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxBalanceValidityChangeEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxBalanceTransferEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxBalanceTopupEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxBalanceThresholdEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxBalanceRolloverEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxBalanceAdjustEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxAutoRenewEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxAccountModifyEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxAccountEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxAccountDeleteEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxAccountCreateEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/Mtx4GDataEvent
        },
        {
          "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/Mtx3GDataEvent
        }
      ],
      "type": "object"
    },
    "mtx_container_name": {
      "description": "MtxResponseEvent",
      "example": "MtxResponseEvent",
      "type": "string"
    },
    "mtx_ext_ver": {
      "description": "Extension Schema Version",
      "example": 2,
      "type": "integer"
    },
    "mtx_result_code": {
      "description": "REST result code",
      "example": 0,
      "type": "integer"
    },
    "mtx_result_text": {
      "description": "Error text from REST call",
      "example": "ok",
      "type": "string"
    },
    "mtx_result_type": {
      "description": "REST method type called",
      "example": "rest call type GET|PUT|POST|DELETE",
      "type": "string"
    },
    "mtx_sys_ver": {
      "description": "System Schema Version",
      "example": 5240,
      "type": "integer"
    },
    "relatedMsgId": {
      "description": "Encoded field used to correlate system wide logging.",
      "example": "some string here",
      "type": "string"
    },
    "result": {
      "description": "Contains error code: 0 = SUCCESS",
      "example": 0,
      "format": "uint32",
      "type": "integer"
    },
    "resultText": {
      "description": "Human-readable description of the result",
      "example": "some string here",
      "type": "string"
    },
    "routeId": {
      "description": "Id of the sub-domain which processed this request.",
      "example": 0,
      "format": "uint16",
      "type": "integer"
    }
  },
  "required": [
    "mtx_container_name"
  ],
  "type": "object"
}

Filter Response by Class Name

You can create class-specific OpenAPI descriptions to build APIs with a subset of the classes. For example, if a hardware provisioning system needs the device APIs only and an on-boarding system needs user, subscription and device APIs, you can specify the className in the request to return only the required services.

Out-of-the-box, you can specify the following classes:

device
event
eventstore
gateway
group
login
pricing
resource_register
service
stream_info
subscriber
subscription
system
task
user

To get the list of classes, use the following service:

GET /rsgateway/data/json/openapi3/api

Specify a className in the request to return only the REST service that matches the className.

Get rsgateway/data/json/openapi3/api/{ApiName}

The ApiName is one of the classes listed above. For example, GET /rsgateway/data/openapi3/api/stream returns:

{
  "openapi": "3.0.0",
  "info": {
    "contact": {
      "email": [email protected],
      "name": "MATRIXX API Support",
      "url": http://www.matrixx.com
    },
    "description": "This is the OpenAPI version of the RS Gateway application.",
    "title": "Matrixx OpenAPI",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": http://localhost:8080/rsgateway/data
    }
  ],
  "tags": [
    {
      "name": "stream_info"
    }
 ],
  "paths": {
    "/openapi/stream_info": {
      "get": {
        "description": "query for list of stream sessions",
        "operationId": "stream_query_session_list",
        "parameters": [
            …
       ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxResponseStreamSessionList
                }
              }
            },
            "description": "success"
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": http://localhost:8080/rsgateway/data/json/openapi3/schema/MtxResponseStreamSessionList
                }
              }
            },
            "description": "Bad Request."
          },
         …
        },
        "summary": "stream",
        "tags": [
          "stream_info"
        ]
      }
    },
…
}

You can append one or more className HTTP parameters to the following URL to filter the response.

http://host:port/rsgateway/data/json/openapi3

For example, to return only the device and subscription services, append ?className=device&classname=subscription to the request URL:

http://host:port/rsgateway/data/json/openapi3?className=subscription&className=device

Note: For classes with an underscore (such as resource_register and stream_info), you must encode the underscore (_). For example:

/rsgateway/data/json/openapi3?className=stream&#95;info