REST Syntax

When using the REST APIS, you should follow the MATRIXX REST syntax rules.

For more information about search terms, see the discussion about REST operation search terms in MATRIXX Subscriber Management API.

REST Syntax Rules

The following MATRIXX REST API syntax rules apply:

REST requests use a URL to identify the MATRIXX resource and the operation to perform. The base URL for XML APIs is:
```
http://host:port/rsgateway/data/v3/
```
The base URL for JSON APIs is:
```
http://host:port/rsgateway/data/json/
```
The base URL for OpenAPI APIs is:
```
http://host:port/rsgateway/data/openapi
```
Where:
- host is the IP address or host name of the pod where RS Gateway is installed.
- port is the port number.
Because a REST request is a URL, there can be no spaces between the parts of a request. The web browser stops reading when it runs across the first space. For example, to look up a subscriber by an IMSI number, the request URL is:
```
http://host:port/rsgateway/data/v3/device/query/imsi/441112408568774
```
If you add any spaces to the IMSI, for example 44 111 240 856 8774, the request would end on 44. This is not an issue with REST calls because the look up key format does not allow them.
Note: The plus character + denotes a space in a URL (for example: ExternalId+10). For this reason, if you include a + in a URL that does not denote a space, such as when including a usec (microsecond) in a timestamp, you must replace the + with %2B. For example, timestamp=2021-01-12T00:50:3.000000+03:00 should be timestamp=2021-01-12T00:50:3.000000%2B03:00. In general, you should apply this rule to any URL parameter (after the ? in the URL). For more information, see the discussion about encoding.
The parameter names in request URLs are case-sensitive. Make certain to use the correct naming format, which is initial capital letters with no spaces between terms. For example, AccessNumber and ExternalId are examples of correct parameter syntax.
In the REST body syntax, the required, conditional, and optional fields follow the generic syntax. Sometimes, some fields are populated as part of the URL itself. These fields are noted in the description of the appropriate REST method. The REST body definitions match the generic specification.
Important: For OpenAPI calls, the REST request body and response are in lower camel case (initial lowercase letter). When specifying filters in OpenAPI requests, the filter name and any fields specified in the filter can be in upper or lower camel case. The REST response always returns results in lower camel case. This applies to predefined and custom filters.
The value(s) supplied in the URL overwrite any values present in the body. For example, if the body for adding a group threshold has a value for <ObjectId> assigned in the <GroupSearchData> element, it is overwritten by the <GroupOID> in the URL.
Search blocks are evaluated in order and the first data element with a value is used as the search key. For example, if both the <ObjectId> and the <ExternalId> are assigned values in the <GroupSearchData> element, only the <ObjectId> is used for the search and the <ExternalId> is ignored.
When a new object such as a device, subscriber, or group is created in the database, a unique object ID is created and returned. If supplied, the ExternalId must be unique within the subscriber database.
The REST requests documented in this guide specify a generic Extension object in the Attr element, for example, MtxSubscriberExtension. Developers must replace this value in the input with the actual name of the external subscriber extension, for example, MyGoldSubscriberExtension.

Important: When serializing floating point numbers, both in XML and JSON, the infinity and -infinity symbols are represented as the strings -infinity and infinity. When processing XML or JSON documents, sometimes these floating point values can be represented as these strings. This is especially likely when dealing with thresholds on balances. You should check to see if the type of the value is a string and if so whether it is infinity or -infinity before trying to use the value as a number.

Optional Values

The assignment of optional field values depends on whether the request creates an object with that field or whether it is a change request.

For calls that create objects, the value for unpopulated optional fields is NotPresent, which sets them to a NULL value.
For calls that change objects, the values for unpopulated optional fields remain set to the value it currently has.

For REST calls operating on a device object, the URL can include a SearchTerm. If you do not specify a SearchTerm (such as <ExternalId>), The SearchTerm is assumed to be an ObjectId. If a qualifier is used, it should immediately precede the search value and be separated from the value by either a space or a plus character (+).

Encoding

When the URL includes special characters such as a hash character (#), you should encode the character. You can encode each special character or you can specify a base 64 encoding level for the entire parameter value.

For encoding individual characters, Character Encoding lists common special characters and their encoding values. The plus character (+) denotes a space in a URL (for example: ExternalId+10). For this reason, if you include a "+" in a URL that does not denote a space, such as when including a timestamp, you must replace + with %2B and : with %3A. For example, timestamp=2021-01-12T00:50:33.000000+03:00 should be encoded as timestamp=2021-01-12T00%3A50%3A33.000000%2B03%3A00. In general, you should apply this rule to any URL parameter (parameters are entered after the ? in the URL).

Table 1. Character Encoding
Character	Name	Encoding	Can % encoding be used?	Alternate Encoding	Reason
_	underscore	_5F	no		Used as an escape character.
+	plus sign in login ID	_2B	no		To avoid issues, use the encoding.
@	(at) sign	_40	yes	%40
;	semicolon	_3B	no		Important: Do not use.
:	colon	_3A	yes	%3A	Do not use colons in URLs. Web browsers should encode these automatically.
=	equal sign	_3D	yes	%3D	Equal signs have meaning in URLs after a question mark.
(	left parentheses	_28	yes	%28	Parentheses have meaning in URLs after a question mark.
)	right parentheses	_29	yes	%29	Parentheses have meaning in URLs after a question mark.
#	hash sign	_23	yes	%23	The hash sign is a special character for web browsers that means retrieve the page and find the bookmark mentioned after the hash sign. MATRIXX suggests that hash signs be encoded.
/	slash	_2F	yes	%2F	Slashes indicate different resources.
\\	backslash	_5C	yes	%5C	Double backslashes have special meaning in the Linux OS shell.

The base 64 encoding level is an optional value that you include in curly brackets { } after the parameter name. For example, to specify a base 64 encoding level for the ExternalId parameter, include {64}+ after the parameter name and then the encoded value as shown here: //localhost:8080/rsgateway/data/json/subscription/ExternalId{64}+c2lwOjsxMjEwMzE3MTI5MThAaW1zLm1uYzM0MC5tY2MzMTMuM2dwcG5ldHdvcmsub3JnLnVzZXI9cGhvbmU

When using CURL to issue the request, you must encode the curly brackets { }. For example, to specify base 64, include %7B64%7D after the parameter name, where:

%7B is {
%7D is }

Schema and Extension Versions

RS Gateway uses the latest MATRIXX Data Container (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.

For OpenApi clients, the system schema version and provider schema version is explicitly part of the request and response payloads. If a client does not include values for these fields, RS Gateway defaults these 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 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 a schema version, it is the highest priority and takes precedence. Specifying the schema version in the header is optional, and works for all JSON, XML, and OpenAPI calls. The methods for setting the schema version in order of precedence are:

The request payload (only for OpenAPI).
Specify the schema and extension versions in headers (For JSON, OpenAPI, and XML REST requests):
- 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).
Version pinning.

The following examples show how to set the schema version or extension version in the header of the call:

curl -v -H "X-MATRIXX-SchemaNumber: 5240" http://localhost:8080/rsgateway/data/json/pricing/status

curl -H "X-MATRIXX-ExtensionNumber: 3" http://localhost:8080/rsgateway/data/json/pricing/status

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.