Usage
YateMMI offers an API to perform some functions and additional requests will be added in the future.
- broadcasting request to multiple nodes. This is the Number portability API.
- proxy request to specific node
- aggregate answers from multiple nodes
- failover. Try same request to multiple nodes until a positive answer is received. An example for this is the query_data request for ucn node.
- store and broadcast
The API offers requests to manage entries in YateNPDB or to query registration information in YateUCN. You can use RESTful or POST requests with JSON content to a specific URI:
For npdb functionality: http://server_ip/mmi/api/v1/npdb
For ucn functionality: http://server_ip/mmi/api/v1/ucn
You can also send request to http://server_ip/mmi/api/v1 directly, but you need to specify “node”:”node_type” in request JSON or in URL.
The API uses a standard reply format:
- Positive response with aggregated info from all nodes: {“code”:0, “answer_list”:[ {“equipment_name“:”Configured name in YateMMI”, “code“:0, “variable_object“:{} }, {“equipment_name”:”Second equipment”, “code”:401, “message”:”Invalid parameters”} ] }
- Negative response {“code”:404,””message”:”Not found”}
Force broadcasting
The requests to add/edit/delete are broadcasted to all npdb nodes configured in YateMMI.
Requests to retrieve series/ported numbers are sent sequentially until one of the tried nodes answers.
To force a get request to be sent to all nodes you can add ‘broadcast’:true to the list of parameters. Example:
POST to http://server_ip/mmi/api/v1 with JSON content to retrieve count of defined series
- Request: {“request”:”get_series”, “node”:”npdb “, “params”: { “broadcast”:true } }
- Response {“code”:0,”answer_list”:[{“equipment_name”:”npdb_1″, “code”:0, “count”:7},{“equipment_name”:”npdb_2″,”code”:0,”count”:5}]}}
POST to mmi/api/v1 with JSON content to retrieve the first two series
- Request: {“request”:”get_series”, “node”:”npdb”, “params”:{“broadcast”:true, “limit”:2}}
- Response: {“code”:0,”answer_list”:[{“”equipment_name”:”npdb_1″,”code”:0,”series”:[{“series_start”:”40744334131″,”series_end”:”40744334139″,”target”:”18750″,”description”:”test”},{“series_start”:”40744334200″,”series_end”:”40744334210″,”target”:”18750″,”description”:””}]},{“equipment_name”:”npdb_2″,”code”:0,”series”:[{“series_start”:”40744334131″,”series_end”:”40744334139″,”target”:”18750″,”description”:”test”},{“series_start”:”40744334200″,”series_end”:”40744334210″,”target”:”18750″,”description”:””}]}]}
Number Portability Series requests
Retrieve series list (limit, offset can be used)
Requests format:
GET mmi/api/v1/npdb/series?limit=x&offset=y
POST to mmi/api/v1/npdb with JSON {“request”:”get_series”, “params”: {“limit”: int, “offset”:int} }
POST to mmi/api/v1 with JSON {“request”:”get_series”, “node”:”npdb “, “params”: {“limit”: int, “offset”:int} }
Response format:
in case of error: { “code”: !0, “message”: …, “extra”: … }
in case of success: { “code”: 0, “answer_list”: [ {“equipment_name”:“name_eq”, “code”:0, “series”:[{“series_start”:NNNNN,”series_end”:NNNNN,”target”:””,”description”:””},{},{} ]}, {} ], “extra”:”Request get_series succeded/failed for name_eq1, ..” }
Retrieve the count of series
Requests format:
GET mmi/api/v1/npdb/series
POST to mmi/api/v1/npdb with JSON {“request”:”get_series”, “params”: {} }
POST to mmi/api/v1 with JSON {“request”:”get_series”, “node”:”npdb”, “params”: {} }
- Response format
- in case of error: { “code”: !0, “message”: …, “extra”: … ]
- in case of success: { “code”: 0, “answer_list”:[ {“equipment_name”:“name_eq”, “code”:0, “count”:5} ], “extra”:”Request get series succeded/failed for ..”}
Retrieve specific series with series_start/series_end
Requests format:
GET mmi/api/v1/npdb/series?series_start:NNNNN,series_end:NNNNN
POST to mmi/api/v1/npdb with JSON {“request”:”get_series”,”params”:{“series_start”:NNNNN,”series_end”:NNNNN}}
POST to mmi/api/v1 with JSON {“request”:”get_series”,”node”:”npdb”, “params”:{“series_start”:NNNNN,”series_end”:NNNNN}}
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”: … }
- in case of success: { “code”: 0, “answer_list”: [ {“equipment_name”:”name_eq”,code”:0,”series”:[{“series_start”:NNNNN,”series_end”:NNNNN,”target”:””,”description”:””}]}, {} ] }
NOTE! For Restful requests using the PUT/POST method, the request will be built to create/update series/ported numbers. In this case, a combination of Restful and JSON may be used – see the example below.
Create series
- Requests format:
- POST mmi/api/v1/npdb/series with JSON content
{“series_start”:NNNNN,”series_end”:NNNNN,”target”:”xxx”,”description”:”yyyy”}
or
POST mmi/api/v1/npdb/series?series_start=NNNNN&series_end=NNNNN& target=xxx&description=yyyy
POST to mmi/api/v1/npdb/series OR to mmi/api/v1 with JSON Request:
{“request”:”set_series”,”node”:”npdb”, “params”:{“series_start”:NNNNN,”series_end”:NNNNN,”target”:”xxx”,”description”:”yyyy”}}
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”:…. }
- in case of success: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”,”code”:0,”count”:1},{},{},…],”extra”:”..” }
Edit series
- Requests format:
- PUT mmi/api/v1/npdb/series with JSON content
{“series_start”:NNNNN,”series_end”:NNNNN,”target”:”xxx”,”description”:”yyyy”}
- PUT mmi/api/v1/npdb/series with JSON content
or
PUT mmi/api/v1/npdb/series?series_start=NNNNN&series_end=NNNNN& target=xxx&description=yyyy
POST to mmi/api/v1/npdb/series OR to mmi/api/v1 with JSON Request:
{“request”:”set_series”, “node”:”npdb”,”params”:{“series_start”:…, “series_end”:…, “target”:”…”,”description”:””}}
Response format:
in case of error: { “code”: !0, “message”: …, “extra”:”” }
in case of success: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”,”code”:0,”count”:1},{}],”extra”:”..”}
Delete series
Requests format:
DELETE mmi/api/v1/npdb/series?series_start=NNNNN&series_end=NNNNN
POST to mmi/api/v1/npdb/series with JSON Request {“request”:”del_series”, “params”: { “series_start”:…, “series_end”:…} }
POST to mmi/api/v1 with JSON {“request”:”del_series”, “node”:”npdb”, “params”: { “series_start”:…, “series_end”:…} }
- Response format:
in case of error: { “code”: !0, “message”: …, “extra”:”” }
in case of success: { “code”: 0, “answer_list”:[“equipment_name”:”name_eq”,”code”:0,”count”:1], “extra”:”..”}
Number Portability Ported numbers requests
Retrieve ported list (limit, offset can be used)
- Requests format:
- GET mmi/api/v1/npdb/ported?limit=x&offset=y
- POST to mmi/api/v1/npdb with JSON {“request”:”get_ported”, “params”: {“limit”: int, “offset”:int} }
- POST to mmi/api/v1 with JSON {“request”:”get_ported”, “node”:””npdb”,”params”: {“limit”: int, “offset”:int}}
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”: … }
- in case of success: { “code”: 0, “answer_list”: [ {“equipment_name”:”name_eq”, “code”:0, “ported”: [{“number”:””,”target”:””},{},{}….]}, {}], “extra”:”Reuqest get_ported succeded/failed for ..”}
Retrieve the count of ported numbers
- Requests format:
- GET mmi/api/v1/npdb/ported
- POST to mmi/api/v1/npdb with JSON content {“request”:”get_ported”, “params”: {} }
- POST to mmi/api/v1 with JSON content {“request”:”get_ported”, “node”:”npdb”, “params”: {} }
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”: … }
- in case of success: { “code”: 0, “answer_list”: [ {“equipment_name”:”name_eq”,”code”:0,”count”:499}, {“equipment_name”:”name_eq”, “code”:0, “count”:200},…. ],”extra”:”…” }
Retrieve specific ported number with number=NNNNN
- Requests format:
- GET mmi/api/v1/npdb/ported?number:NNNNN
- POST to mmi/api/v1/npdb with JSON content {“request”:”get_ported”,”params”:{“number”:NNNNN}}
- POST to mmi/api/v1 with JSON content {“request”:”get_ported”,”node”:”npdb”, “params”:{“number”:NNNNN}}
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”: … }
- in case of success: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”, “code”:0, “ported”: [ {},{},{},…. ]}],”extra”:”..” }
Create ported number
Requests format:
POST mmi/api/v1/npdb/ported with JSON content
{“number”:NNNNN,”target”:”xxx”}
or
POST mmi/api/v1/npdb/ported?number=NNNNN&target=xxx
- POST to mmi/api/v1 JSON Request:
{“request”:”set_ported”, “node”:”npdb’, “params”:{“number”:NNNNN,”target”:”xxx”}}
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”:…. }
- in case of success: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”, “code”:0, “count”:1},{},{},…],”extra”:”..” }
Update ported number ( if the number doesn’t exist it will be inserted )
- Requests format:
- PUT mmi/api/v1/npdb/ported with JSON content
{“number”:NNNNN,”target”:”xxx”}
- PUT mmi/api/v1/npdb/ported with JSON content
or
PUT mmi/api/v1/npdb/ported?number=NNNNN&target=xxx
PUT JSON Request:
{“request”:”set_ported”, “params”:{“number”:…, “target”:”…”}}
POST to mmi/api/v1 {“request”:”set_ported”, “node”:”npdb”,”params”:{“number”:…, “target”:”…”}}
Response format:
in case of error: { “code”: !0, “message”: …, “extra”:”” }
in case of success: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”, “code”:0, “count”:1},{},{},…],”extra”:”..” }
Delete ported number
- Requests format:
- DELETE mmi/api/v1/npdb/ported?number=NNNNN
- POST to mmi/api/v1/npdb {“request”:”del_ported”, “params”: { “number”:… }
- POST to mmi/api/v1 {“request”:”del_ported”, “node”:”npdb”, “params”: { “number”:… }
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”:”” }
- in case of success: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”, “code”:0, “count”:1},{},{},…],”extra”:”..” }
Search number in ported or series
- Requests format:
- GET mmi/api/v1/npdb/search_ported?number=NNNNN
- POST to mmi/api/v1/npdb {“request”:”search_ported”, “params”: { “number”:… }
- POST to mmi/api/v1 {“request”:”search_ported”, “node”:”npdb”, “params”: { “number”:… }
- to request error from nodes of number is not found add “required”:true in “params” or in URL when using GET request
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”:”” }
- in case of success ported or series will appear in response: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”, “code”:0, “ported”:{}, “series”:{} },{},{},…],”extra”:”..” }
- to request error if not found { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”, “code”:404, “message”:”Entity not found”},{}],”extra”:”..”}
Equipment requests
Receive notification that an equipment started
- Request format
- GET / POST to mmi/api/v1/node_starts?hostname=$hostname
- POST to mmi/api/v1 with JSON content { “request”:”node_starts”, “params”:{“hostname”:”$hostname”}
- Response format
- in case of error: { “code”: !0, “message”: …, “extra”:”” }
- in case of success: { “code”: 0 }
Requests to query information
Query data sessions in configured YateUCNs
- Requests format. Request ‘query_data’ with params required:true will be sent to all UCN nodes
- GET mmi/api/v1/ucn/query_data?msisdn=NNNNN // you need to specify imsi, msisdn or address
- POST to mmi/api/v1/ucn {“request”:”query_data”, “params”: { “imsi”:””, “msisdn”:””, “address”:””}} // just one of the fields in params is required
- POST to mmi/api/v1 {“request”:”query_data”, “node”:”ucn”, “params”: { “imsi”:””, “msisdn”:””, “address”:”” }} // just one of the fields in params is required
- Response format:
- in case of error: { “code”: !0, “message”: …, “extra”:”” }
- in case of success: { “code”: 0, “answer_list”:[{“equipment_name”:”name_eq”, “code”:0, “data_session”:{ “imsi”:”001010123456789″,“msisdn”:”88270089″,“apn”:”internet”,“plmn”:”00101″,“sgsn”:”192.168.0.2″,“ipv4″:”10.225.0.82”,“ipv6″:”fd00:1:0:2::”,“qci”:9,“redirect”:true}] ],”extra”:”Request query_data succeeded for name_eq” }