YateHSS/HLR, YateUCN, YateSMSC and YateUSGW all offer a JSON API for configuration. You can use this API to:
The JSON API is accessed via the management IP address associated to each server. This IP address is provisioned by the MMI (Mobile Management Interface) or set by hand.
Click here to find a demo of the YateMMI, with preconfigured YateHSS/HLR, YateUCN and YateSMSC equipments (contact us for a demo account).
YateMMI is the interface that allows configuring the network and the SS7 settings for all Yate-based products: YateUCN, YateHSS/HLR and YateSMSC.
Request format
The basic way of making an API requests is to use the JSON format.
A subset of requests and parameters are also accessible via a JSON REST API.
JSON format
To use it, make a HTTPS POST request with “Content-Type” header “application/json” and the “X-Authentication” header set to a pre-configured value (Mobile API Secret).
Path for requests: https://ip_management/api.php
Requests have the following format:
{ “request”: request_name, “node”: node_name, “params”: {..} }
Example of node_names:
Depending on the params given you retrieve:
{} — retrieve count
In response you must look for “count” key if request is successful.
a part of the objects
{ “limit”: , “offset”: }
{ “name”: / “object_id”: /.. } — retrieve specific object by id/name/..
REST format
An alternative method supporting just a limited set of parameters is to use JSON REST API requests.
To use it make a GET or POST request to the same path to api.php and provide the “X-Authentication” header if required.
Note that responses will still be in JSON format.
REST mapping
The REST access methods internally map the parameters to a JSON structure according to the following rules:
- Of the “params” object if the name contains no slash “/” character
- Of an object inside “params” whose name is obtained by replacing slashes with dots
- Value null is converted to a null object
- Values true and false are converted to a boolean value
- Values representing integers are converted to a numeric value
Arrays, repeated parameters or different conversions are not supported, you will need the JSON API for that.
Example:
REST: http://…/api.php?request=query_stats&node=hss&details=true
JSON: {“request”:”query_stats”,”node”:”hss”,”params”:{“details”:true}}
It is also possble to set request and optionally node as path parameters like this:
Response format
The API always returns a JSON object with the “Content-Type” set to “application/json” or “text/x-json”.
In case of success:
{ “code”: 0 }
{ “code”: 0, “object_name”: [ {}, {} ] } // array of objects of the specific type. Ex: subscriber, pdn
{ “code”: 0, “count”: } // count of objects of specific type when no parameters were specified
In case of an error:
{ “code”: !0, “message”: … }
Turn to the next pages, JSON API for Configuration and JSON API for Subscriber Management to find out more about the supported requests and their parameters.
Error codes
There are two types of errors, as seen below.
HTTP errors
Errors in the JSON response
Error code:
| Category (fatal/retry) | Code | Description | Example |
|---|---|---|---|
| Retry once | 200 | Request not handled | Request 'no_such' not handled by Yate |
| Retry once | 201 | Configuration error | No node plugin is installed |
| Retry | 300 | Generic error | |
| Fatal | 400 | Generic error | |
| Fatal / needs correction | 401 | Invalid parameter(s) value | Invalid 'port' value '-3': out of range |
| Fatal / needs correction | 402 | Missing mandatory parameter(s) | Missing 'port' parameter |
| Fatal / needs correction | 403 | Duplicate entity | MSISDN is already in use |
| Fatal / needs correction | 404 | Entity not found | No such operator |
| Fatal / needs correction | 405 | Entity in use | Profile still in use |
| Fatal / needs maintenance | 500 | Incompatibility | Expecting application version '1.3-2' |
| Fatal / needs maintenance | 501 | File system error | Failed to save file '/usr/local/etc/accfile.conf' |
| Fatal / needs maintenance | 502 | Database query execution error | Database error |
Common requests
Several requests are supposed to be handled by all node types. The properties in the returned JSON object may differ though.
Request: set_ss7_node
This request is used to configure the SS7 settings for various equipment (ex: YateHSS/HLR,YateSMSC, YateUCN etc.).
Requests
{
"request": "set_ss7_node",
"node": "The node for which SS7 settings are configured. Ex: hss",
"params": {
"comment__local": "Information about the local node (the actual equipment that you are configuring). . The information about the local node is organized in 'common' object (common settings for the network, but also equipment specific information).",
"local": {
"common": {
"dialect": "ITU/ANSI",
"netindicator": "national/reservednational/international",
"pointcode": "Local pointcode, integer representation, range depends on dialect.",
"gt": "Array of local GT. The first element is the GT we are sending from.",
"hlr": "Optional, HLR number (GT) returned in Update Location.",
"msisdn": "Array of MSISDN prefixes to which the HLR will respond.",
"ip": "Local IP address for signaling protocols. Array or comma separated list.",
"sccp_tt": "Boolean. Optional, use Translation Type in SCCP messages, defaults to false.",
"sccp_pc": "Boolean. Optional, use Point Code in SCCP source address, defaults to false."
}
},
"comment__linksets": "Configures the linksets and links to the STP",
"linksets": [
{
"type": "M2PA/M3UA",
"comment__type": "For M3UA pointcode is optional. Either pointcode and/or route must be present",
"pointcode": "Adjacent point code, integer representation, range depends on dialect",
"route": "Optional array of PCs in integer representation to route through this STP. The string 'default' may be used as point code to indicate a default route. E.g. route: [23, 'default']",
"comment__links": "M2PA: list of links. M3UA: 1 entry with connection data",
"links": [
{
"ip": "Remote IP address. Array or comma separated list.",
"port": "Integer: 1-65535. Port on the adjacent node.",
"local_ip": "Array of Optional local IP address (use common if missing).",
"local_port": "Optional. Integer: 1-65535. Local port number. Ignored for M3UA. Otherwise: use remote port as default if missing.",
"dscp": "Optional socket DSCP (string or integer)",
"comment__sctp_params": "Optional SCTP params. All params are optional. All integer params are unsigned. See lksctp.conf for info.",
"sctp_params": {
"rto_initial": "Initial Retransmission Timeout. Format: NNN. Numeric value, maximum 3 digits.",
"rto_min": "Minimum Retransmission Timeout. Format: NNN. Numeric value, maximum 3 digits.",
"rto_max": "Maximum Retransmission Timeout. Format: NNN. Numeric value, maximum 3 digits.",
"max_retrans": "Maximum number of retransmissions. Format: NNN. Numeric value, maximum 3 digits.",
"hb_interval": "Heartbeat interval in milliseconds. Defaults to 30000 for Diameter transport.",
"hb_enabled": "Boolean. Enable Heartbeat. Defaults to true.",
"sack_delay": "Selective Acknowledgement delay. Between 0 and 500ms. Format: NNN. Numeric value, maximum 3 digits.",
"sack_freq": "Selective Acknowledgement frequency. Format: NNN. Numeric value, maximum 3 digits."
}
}
],
"aspid": "M3UA only. Number. Optional ASP identifier (unsigned 32 bit)",
"contexts": "M3UA only. Number. Optional Array of routing context numbers (unsigned 32 bit)",
"traffic": "M3UA only. String. Optional traffic type. Possible values: unused/override/loadshare/broadcast",
"network_appearance": "M3UA only. Number. Optional network appearance (unsigned 32 bit)"
}
],
"comment__gt_route": "Configures the GT routes table",
"gt_route": [
{
"pc": "Number. Remote point code (must a configured one if there is no default route)",
"prefix": "Number. List of GT prefixes to route to this PC, can be just [ '*' ]"
}
]
}
}
Responses
Errors
Examples: set_ss7_node
Configure ss7 settings.
Request
{
"request": "set_ss7_node",
"node": "hss",
"params": {
"local": {
"common": {
"dialect": "ANSI",
"netindicator": "national",
"pointcode": 33,
"gt": [
"8820033",
"88200330"
],
"msisdn": [
"8827"
],
"ip": "192.168.168.225"
}
},
"linksets": [
{
"type": "M2PA",
"pointcode": 1,
"links": [
{
"ip": "192.168.168.222",
"port": 4533,
"local_port": 4633
}
]
},
{
"type": "M2PA",
"pointcode": 101,
"links": [
{
"ip": "192.168.168.222",
"port": 4733,
"local_port": 4833
}
]
}
],
"gt_route": [
{
"pc": 1,
"prefix": [
"882",
"*"
]
},
{
"pc": 101,
"prefix": [
"40",
"*"
]
}
],
"restart": true
}
}Response
Request: set_diam_node
This request is used to configure the diameter settings for various equipment (ex: YateHSS/HLR, YateUCN etc.).
Requests
{
"request": "set_diam_node",
"node": "hss",
"params": {
"comment__local": "Information about the local node (the actual equipment that you are configuring). The information about the local node is organized in 'common' object (settings for the network, but also equipment specific information).",
"local": {
"common": {
"relay_route_priority": "Number. Optional default route priority for remote nodes advertising. Relay application. Negative: disable. Defaults to 100."
}
},
"comment__identities": "Configure local nodes",
"identities": [
{
"node": "Node identity (realm(domain_name)/host(host_name)). Ex: example.com/hss.example.com",
"role": "String. Optional name of special role of this node",
"default_priority": "Number. Optional priority to use this node if no other matches. Default 0 (disabled).",
"default_realm_priority": "Number. Optional priority to use this node if only realm matches. Default 0 (disabled)."
}
],
"comment__listeners": "Configure the listeners",
"listeners": [
{
"local_ip": "Array of Local IP to bind to.",
"local_port": "Optional local port number, protocol default port will be used if missing",
"ipv6only": "Boolean. Optional. Accept IPv6 only connections. Ignored if local_ip is IPv4",
"dscp": "Optional socket DSCP (string or integer)",
"sctp_params": {
"rto_initial": "Number. Unsigned. Optional. See lksctp.conf for info.",
"rto_min": "Number. Unsigned. Optional. See lksctp.conf for info.",
"rto_max": "Number. Unsigned. Optional. See lksctp.conf for info.",
"max_retrans": "Number. Unsigned. Optional. See lksctp.conf for info.",
"hb_interval": "Number. Unsigned. Optional. See lksctp.conf for info.",
"hb_enabled": "Boolean",
"sack_delay": "Number. Unsigned. Optional. See lksctp.conf for info.",
"sack_freq": "Number. Unsigned. Optional. See lksctp.conf for info."
},
"comment_accept": "Optional, configure accept rule(s). If present and not empty it will restrict the list of local nodes. Handled by this listener. All identities will be handled by this listener if accept is empty",
"accept": [
{
"node": "Node to accept, must be a configured identity",
"accept_node": "Optional remote node(s) to accept. String: RegExp to match node(s) to accept / Array: Only remote nodes matching it will be accepted. If present and not empty only listed remote nodes will be accepted.",
"default_route": "Number. Optional default route priority for accepted connections"
}
]
}
],
"comment__connections": "Information about the local node (the actual YateHSS/HLR server that you are configuring). The information about the local node is organized in 'common' object (settings for the network, but also equipment specific information).",
"connections": [
{
"node": "Local identity. The name of a node configured in identities.",
"remote_host": "Diameter remote (peer) host name. Ex: FQDN",
"ip": "Optional Array of IP address to connect to. Remote host will be used if missing.",
"port": "Optional port to connect to. Protocol default will be used if missing",
"local_ip": "Optional Array of local IP to bind on",
"dscp": "Optional socket DSCP (string or integer)",
"comment__sctp_params": "Optional SCTP params. All params are optional. All integer params are unsigned. See lksctp.conf for info",
"sctp_params": {
"rto_initial": "Number.",
"rto_min": "Number.",
"rto_max": "Number.",
"max_retrans": "Number.",
"hb_interval": "Number.",
"hb_enabled": "Boolean",
"sack_delay": "Number.",
"sack_freq": "Number."
},
"default_route": "Number. Optional default route priority"
}
]
}
}
Responses
Errors
Examples: set_diam_node
Configure diameter settings.
Request
{
"request": "set_diam_node",
"node": "hss",
"params": {
"identities": [
{
"node": "epc.mnc008.mcc246.3gppnetwork.org/YateHSS.epc.mnc008.mcc246.3gppnetwork.org",
"default_priority": 0,
"default_realm_priority": 0
}
],
"listeners": [
{
"local_ip": [
"192.168.50.234"
],
"ipv6only": false,
"sctp_params": {
"hb_interval": 30000,
"hb_enabled": true,
"sack_freq": 10
}
}
],
"connections": [
{
"node": "epc.mnc008.mcc246.3gppnetwork.org/YateHSS.epc.mnc008.mcc246.3gppnetwork.org",
"local_ip": [
"192.168.50.235"
],
"ip": [
"192.168.50.236"
],
"port": null,
"remote_host": "yatebtstest.com",
"sctp_params": {
"hb_interval": 30002,
"hb_enabled": true,
"sack_freq": 10
}
},
{
"node": "epc.mnc008.mcc246.3gppnetwork.org/YateHSS.epc.mnc008.mcc246.3gppnetwork.org",
"local_ip": [
"192.168.50.237"
],
"ip": [
"192.168.50.238"
],
"port": null,
"remote_host": "yatebts2.com",
"sctp_params": {
"hb_interval": 30000,
"hb_enabled": true,
"sack_freq": 10
}
},
{
"node": "epc.mnc008.mcc246.3gppnetwork.org/YateHSS.epc.mnc008.mcc246.3gppnetwork.org",
"local_ip": [
"192.168.50.221"
],
"ip": [
"192.168.50.222"
],
"port": null,
"remote_host": "yatedra2.epc.mnc008.mcc246.3gppnetwork.org",
"sctp_params": {
"hb_interval": 30000,
"hb_enabled": true,
"sack_freq": 10
}
}
]
}
}Response
Request: set_regexroute
This request is used to configure the regexroute settings for various equipment (ex: YateHSS/HLR, YateUCN etc.).
Requests
{
"request": "set_regexroute",
"node": "ucn",
"params": {
"rules": [
{
"name": "string, optional. Name of template used for adding comments in the written file to make reading easier.",
"rules": "string, mandatory. Contains rules that are to be written for this template in regexroute. The string must be in valid Yate configuration format."
},
"..."
]
}
}
Responses
Errors
Examples: set_regexroute
Set regexroute rules for hss.
Request
{
"request": "set_regexroute",
"node": "hss",
"params": {
"rules": [
{
"name": "route_msrn",
"rules": "[default]\n${roaming}^80080000=sip/sip:+${roaming}@127.0.0.1;oconnection_id=gmsc\n${roaming}^80080111=sip/sip:+${roaming}@127.0.0.2;oconnection_id=gmsc\n${roaming}^80080002=sip/sip:+${roaming}@127.0.0.3;oconnection_id=gmsc"
}
]
}
}Response
Request: set_javascript
This request is used to configure the javascript scripts for various equipment (ex: YateHSS/HLR, YateUCN etc.).
Requests
{
"request": "set_javascript",
"node": "hss",
"params": {
"scripts": [
{
"name": "string, optional. Name of script used for adding comments in the written file to make reading easier.",
"rules": "string, mandatory. Contains rules that are to be written for this template in regexroute. The string must be in valid Yate configuration format.",
"script": "string, mandatory. Contains the JS script that will be written for this template in javascript. The string must be in valid Yate configuration format."
},
"..."
]
}
}
Responses
Errors
Examples: set_javascript
Basic request, successful response
Request: get_api_version
Retrieve the version of the API
Examples: get_api_version
Basic request, successful response
Request: get_oem_serial
Retrieve the OEM serial number of the machine
Examples: get_oem_serial
Basic request, successful response
Request: get_host_name
Retrieves the name of the host as configured locally.
Examples: get_host_name
Example for unconfigured node.
Request: get_net_address
Retrieves a list of network interface information from the equipment.
Examples: get_net_address
Example containing also loopback.
Example having loopback and PGW tunnel removed from response.
Request: get_node_type
Get a list of all installed node types with their versions
Examples: get_node_type
Retrieve installed node type and software version.
Request: get_node_status
Retrieves operational status and software version of the node.
Examples: get_node_status
Retrieve filtered logs for hss of level 'note'.
Request: get_node_logs
Retrieve filtered logs of a node since the last start
Examples: get_node_logs
Retrieve filtered logs for hss of level 'note'.
Request: get_node_config
Retrieve a configuraion file or an archive of all config files of a node
Requests
This request has multiple formats in which it can be sent:
{
"request": "get_node_config",
"node": "Type of node to retrieve configs from"
}
{
"request": "get_node_config",
"node": "Type of node to retrieve configs from",
"params": {
"file": "Name of the config file to retrieve"
}
}
Responses
Errors
Examples: get_node_config
Retrieve archive of all config files for hss.
Retrieve yate-hss.conf configuraion file for hss.
Request: node_restart
Restarts the specified node of the equipment at the Operating System service level.
Examples: node_restart
Restart hss node.
Request: node_reload
Reload the configuration of a running node
Examples: node_reload
Reload the configuration for hss node.
Request: query_stats
Retrieve statistics from a running node
Examples: query_stats
Retrieve statistics from hss node
Request: info
Retrieve a list of API requests with their description
Examples: info
Retrieve common requests list, response truncated for brevity
Request: info_all
Retrieve a list of API requests with their detailed description
Examples: info_all
Retrieve list of common API requests with their detailed description
This documentation was generated on 09 May 2024