JSON API

From YateBTS
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 MMI, the interface that allows configuring the network and the SS7 settings for the YateHSS/HLR and the YateUCN servers. Username and password are both 'admin'

Request format

To use it, make a HTTPS POST request with "Content-Type" header "application/json" and "Mobile-API-Secret" header set to a pre-configured value.

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/..

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 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"
 }
}

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"
}


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 ...
 }
}