JSON API

From YateBTS
Revision as of 13:48, 13 December 2016 by Monica (Talk | contribs)

Jump to: navigation, search

YateHSS/HLR, YateUCN and YateSMSC 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.

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, "params": {..} }

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

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