JSON API

From YateBTS
Revision as of 19:21, 26 July 2018 by Paulc (Talk | contribs) (→‎REST mapping)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

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 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
{ "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 REST 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&param=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: 

http://.../api.php/query_stats?node=hss&details=true
 or even
http://.../api.php/query_stats/hss?details=true

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) 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: get_node_status

Retrieves operational status and software version of the node.

Request structure: 

{ "request":"get_node_status", "node":"node_type" }

Successful response, service status reported in status: 

{"code":0,
 "status":{
   "operational":true/false,
   "level":"debug level name",
   "state":"Short text description",
   "service":"Service status as reported by Linux\n"
 },
 "version":"yate-package-version"
}

Unsuccessful response, service status reported in message text: 

{"code":200,
 "message":"Cannot connect to Yate on port 'NNNN'.\nService status as reported by Linux\n",
 "version":"yate-package-version"
}

Request: query_stats

Retrieves node statistics for the specified node of the equipment.

Request structure: 

{ "request":"query_stats", "node":"node_type" }

Response structure: 

{"code":0,
 "stats":{
   "engine":{
      ... Yate engine specific statistics ...
   },
   "uptime":{
      ... Yate engine uptime and CPU usage ...
   },
   ... product specific statistics grouped by component ...
 }
}


Request: restart_node

Restarts the specified node of the equipment at the Operating System service level.

Request structure: 

{ "request":"restart_node", "node":"node_type" }

Response structure: 

{"code":0, "restarted": "node_type" }

Will return an error if the node type is invalid or if the service cannot be restarted.


Request: get_api_version

Retrieves the API version from the equipment. This request is not node specific.

Request structure: 

{ "request":"get_api_version" }

Response structure: 

{"code":0, "api_version": "version of the yate-common package" }

In case the API version is unavailable the returned value is "unknown".


Request: get_oem_serial

Retrieves the OEM serial number from the equipment. This request is not node specific.

Request structure: 

{ "request":"get_oem_serial" }

Response structure: 

{"code":0, "serial": "serial number of the equipment" }

In case the OEM file is present but the number is missing will return "serial":null.


Request: get_net_address

Retrieves a list of network interface information from the equipment. This request is not node specific.

Request structure: 

{ "request":"get_net_address", "params": { "filtered": true/false } }

Response structure: 

{"code":0,
 "net_address": [
   { "interface": "name-of-the-interface",
     "ethernet": "XX:XX:XX:XX:XX:XX",
     "ipv4": [
       {
         "address": "192.168.0.1",
         "netmask": "255.255.255.0"
       },
       {
         "address": "192.168.100.1",
         "netmask": "255.255.255.0",
         "alias": "0"
       },
       ...
     ]
     "ipv6": [
       {
         "address": "fd00::1",
         "prefixlen": 64
       },
       ...
     ],
     "mtu": 1500
   },
   { "interface": "another",
     ...
   }
 ]
}

By default the interfaces are filtered, loopback and tunnels created by Yate are not returned. To return all interfaces set "filtered":false

Retrieved from "https://wiki.yatebts.com/index.php?title=JSON_API&oldid=3673"