JSON API

YateHSS/HLR, YateUCN, YateSMSC and YateUSGW all offer a JSON API for configuration. You can use this API to:

  • configure the general network settings
  • set the SS7/Diameter settings of the server (both YateHSS/HLR and YateUCN)
  • set the SS7/SMPP settings for YateSMSC
  • define service (CS,PS,EPS,IMS) and SIM profiles (YateHSS/HLR)
  • manage subscribers (YateHSS/HLR)
  • request delivery of sms (YateSMSC)

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:

  • "hss"
  • "ucn"
  • "sdr"

Depending on the params given you retrieve:

  • count of objects of a certain type

{} — retrieve count

In response you must look for “count” key if request is successful.

  • a part of the objects

a part of the objects
{ “limit”: , “offset”: }

  • specific objects by providing the id/name/other filtering criteria

{ “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.

  • For GET parameters need to be part of the ULR like: api.php?request=REQ_NAME&node=NODE¶m=VALUE&...
  • For PUT the body should contain the parameters in MIME type application/x-www-form-urlencoded

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:

  • request and node are mapped as properties of the root object
  • All other parameters are mapped as properties
  • 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
  • Type conversions
  • 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

  • 405 (Method not allowed) - You didn't use HTTP POST method
  • 415 (Unsupported Media Type/Unparsable JSON content) - Content type is not "application/json" or "text/x-json" or JSON could not be decoded
  • 500 (Internal server error) - This could be a server configuration issue or you have multiple nodes installed on that machine and you didn't specify 'node' in your request.

Errors in the JSON response

Error code:

Category (fatal/retry)CodeDescriptionExample
Retry once 200Request not handledRequest 'no_such' not handled by Yate
Retry once201Configuration errorNo node plugin is installed
Retry300Generic error
Fatal400Generic error
Fatal / needs correction 401Invalid parameter(s) value Invalid 'port' value '-3': out of range
Fatal / needs correction402Missing mandatory parameter(s)Missing 'port' parameter
Fatal / needs correction403Duplicate entityMSISDN is already in use
Fatal / needs correction404Entity not foundNo such operator
Fatal / needs correction405Entity in useProfile still in use
Fatal / needs maintenance500IncompatibilityExpecting application version '1.3-2'
Fatal / needs maintenance501File system errorFailed to save file '/usr/local/etc/accfile.conf'
Fatal / needs maintenance502Database query execution errorDatabase 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.).
{
    "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 [ '*' ]"
            }
        ]
    }
}
Examples: set_ss7_node
Configure ss7 settings.
{
    "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
    }
}

Request: set_diam_node

This request is used to configure the diameter settings for various equipment (ex: YateHSS/HLR, YateUCN etc.).
{
    "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"
            }
        ]
    }
}
Examples: set_diam_node
Configure diameter settings.
{
    "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
                }
            }
        ]
    }
}

Request: set_regexroute

This request is used to configure the regexroute settings for various equipment (ex: YateHSS/HLR, YateUCN etc.).
{
    "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."
            },
            "..."
        ]
    }
}
Examples: set_regexroute
Set regexroute rules for hss.
{
    "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"
            }
        ]
    }
}

Request: set_javascript

This request is used to configure the javascript scripts for various equipment (ex: YateHSS/HLR, YateUCN etc.).
{
    "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."
            },
            "..."
        ]
    }
}
Examples: set_javascript
Basic request, successful response
{
    "request": "set_javascript",
    "node": "hss",
    "params": {
        "scripts": [
            {
                "name": "test",
                "script": "console.log(\"test\");"
            }
        ]
    }
}

Request: get_api_version

Retrieve the version of the API
{
    "request": "get_api_version"
}
Examples: get_api_version
Basic request, successful response
{
    "request": "get_api_version"
}

Request: get_oem_serial

Retrieve the OEM serial number of the machine
{
    "request": "get_oem_serial"
}
Examples: get_oem_serial
Basic request, successful response
{
    "request": "get_oem_serial"
}

Request: get_net_address

Retrieves a list of network interface information from the equipment.
{
    "request": "get_net_address",
    "params": {
        "filtered": "Boolean. If true removes loopback and PGW tunnels created by Yate. (optional, default true)."
    }
}
Examples: get_net_address
Example containing also loopback.
{
    "request": "get_net_address",
    "filtered": false
}
Example having loopback and PGW tunnel removed from response.
{
    "request": "get_net_address",
    "filtered": true
}

Request: get_node_type

Get a list of all installed node types with their versions
{
    "request": "get_node_type"
}
Examples: get_node_type
Retrieve installed node type and software version.
{
    "request": "get_node_type"
}

Request: get_node_status

Retrieves operational status and software version of the node.
{
    "request": "get_node_status",
    "node": "Type of node to request status from"
}
Examples: get_node_status
Retrieve filtered logs for hss of level 'note'.
{
    "request": "get_node_status",
    "node": "dra"
}

Request: get_node_logs

Retrieve filtered logs of a node since the last start
{
    "request": "get_node_logs",
    "node": "Type of node to retrieve logs from",
    "params": {
        "level": "Symbolic or numeric maximum level (optional)",
        "lines": "Number of lines to retrieve (optional, default 50)"
    }
}
Examples: get_node_logs
Retrieve filtered logs for hss of level 'note'.
{
    "request": "get_node_logs",
    "node": "hss",
    "params": {
        "level": "note"
    }
}

Request: get_node_config

Retrieve a configuraion file or an archive of all config files of a node
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" } }
Examples: get_node_config
Retrieve archive of all config files for hss.
{
    "request": "get_node_config",
    "node": "hss"
}
Retrieve yate-hss.conf configuraion file for hss.
{
    "request": "get_node_config",
    "node": "hss",
    "params": {
        "file": "yate-hss.conf"
    }
}

Request: node_restart

Restarts the specified node of the equipment at the Operating System service level.
{
    "request": "node_restart",
    "node": "Type of node to restart"
}
Examples: node_restart
Restart hss node.
{
    "request": "node_restart",
    "node": "hss"
}

Request: node_reload

Reload the configuration of a running node
{
    "request": "node_reload",
    "node": "Type of node to reload"
}
Examples: node_reload
Reload the configuration for hss node.
{
    "request": "node_reload",
    "node": "hss"
}

Request: query_stats

Retrieve statistics from a running node
{
    "request": "query_stats",
    "node": "Type of node to query"
}
Examples: query_stats
Retrieve statistics from hss node
{
    "request": "query_stats",
    "node": "hss"
}

Request: info

Retrieve a list of API requests with their description
This request has multiple formats in which it can be sent:
{
    "request": "info",
    "node": "Type of node to retrieve APIs from"
}
{ "request": "info" }
Examples: info
Retrieve common requests list, response truncated for brevity
{
    "request": "info"
}

Request: info_all

Retrieve a list of API requests with their detailed description
This request has multiple formats in which it can be sent:
{
    "request": "info_all",
    "node": "Type of the node to retrieve the full list of APIs from"
}
{ "request": "info_all" }
Examples: info_all
Retrieve list of common API requests with their detailed description
{
    "request": "info_all"
}
This documentation was generated on 29 October 2020