Introduction to the NMS Prime API
The NMS Prime API is REST/JSON based. Using the API one can create, modify, delete or inspect database objects. The user input will be validated prior to storing it. If the validation fails a corresponding error message will be returned, informing the user which field failed validation.
A user is authenticated using BasicAuth. Currently only the user with the email address "api@localhost" is allowed to access the API. This user is authorized to create, modify, delete or inspect any database object. In future there will be the role "api" which can be assigned to any user having API access. Furthermore one will be able to grant the various API users different fine-grained access rights for the database objects, just like it is possible for the normal WebGUI.
For most users the most interesting objects will be:
- Qos
- Contract
- Modem
- MTA
- Telephone Number
By virtue of the HTTP/REST transport protocol many different clients can be used. We will only use curl and python in the upcoming examples.
| Drawio | |||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
Inspecting database objects
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
# GET all Qos objects
$ curl -u api@localhost:secret https://localhost:8080/admin/api/v0/Qos
[{"id":1,"created_at":"2015-12-16 14:20:25","updated_at":"2018-06-15 18:05:14","deleted_at":null,"ds_rate_max":100,"us_rate_max":10,"ds_rate_max_help":104857600,"us_rate_max_help":10485760,"name":"100M"},{"id":2,"created_at":"2016-02-15 14:11:40","updated_at":"2018-06-15 18:05:14","deleted_at":null,"ds_rate_max":25,"us_rate_max":2,"ds_rate_max_help":26214400,"us_rate_max_help":2097152,"name":"25M"},{"id":3,"created_at":"2016-02-15 14:11:55","updated_at":"2018-06-15 18:05:14","deleted_at":null,"ds_rate_max":6,"us_rate_max":2,"ds_rate_max_help":6291456,"us_rate_max_help":2097152,"name":"6M"},{"id":6,"created_at":"2018-01-11 13:29:00","updated_at":"2018-06-15 18:05:14","deleted_at":null,"ds_rate_max":50,"us_rate_max":2,"ds_rate_max_help":52428800,"us_rate_max_help":2097152,"name":"50 M"},{"id":7,"created_at":"2018-01-26 14:00:36","updated_at":"2018-06-15 18:05:14","deleted_at":null,"ds_rate_max":1,"us_rate_max":0.5,"ds_rate_max_help":1048576,"us_rate_max_help":524288,"name":"1 M"}]
# GET Qos object with a certain id (6)
$ curl -u api@localhost:secret https://localhost:8080/admin/api/v0/Qos/6
{"id":6,"created_at":"2018-01-11 13:29:00","updated_at":"2018-06-15 18:05:14","deleted_at":null,"ds_rate_max":50,"us_rate_max":2,"ds_rate_max_help":52428800,"us_rate_max_help":2097152,"name":"50 M"} |
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
import json
import requests
# initialize session and authenticate using BasicAuth
session = requests.Session()
session.auth = ('api@localhost', 'secret')
# GET all Qos objects
r = session.get('https://localhost:8080/admin/api/v0/Qos')
# GET Qos object with a certain id (6)
r = session.get('https://localhost:8080/admin/api/v0/Qos/6')
# GET all Contract objects
r = session.get('https://localhost:8080/admin/api/v0/Contract')
# GET Contract object with a certain id (500000)
r = session.get('https://localhost:8080/admin/api/v0/Contract/500000')
# GET all Modem objects
r = session.get('https://localhost:8080/admin/api/v0/Modem')
# GET Modem object with a certain id (100001)
r = session.get('https://localhost:8080/admin/api/v0/Modem/100001')
# GET all Mta objects
r = session.get('https://localhost:8080/admin/api/v0/Mta')
# GET Mta object with a certain id (300001)
r = session.get('https://localhost:8080/admin/api/v0/Mta/300001')
# GET all Phonenumber objects
r = session.get('https://localhost:8080/admin/api/v0/Phonenumber')
# GET Phonenumber object with a certain id (300001)
r = session.get('https://localhost:8080/admin/api/v0/Phonenumber/300001')
# Search using arbitrary model attributes
# returns e.g. cm-100000 (00:11:22:33:44:55) and cm-100001 (66:77:88:99:AA:BB) of contract 500001
r = session.get('https://localhost:8080/admin/api/v0/Modem?contract_id=500001')
# returns only cm-100000 (00:11:22:33:44:55)
r = session.get('https://localhost:8080/admin/api/v0/Modem?contract_id=500001&mac=00:11:22:33:44:55')
print(r.text) |
Creating, modifying and deleting database objects
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
import json
import requests
session = requests.Session()
session.auth = ('api@localhost', 'secret')
# GET description of all fields of this object, the ones with an asterisk (*) must be provided, otherwise validation will fail
r = session.get('https://localhost:8080/admin/api/v0/Contract/create')
# CREATE a contract
r = session.post('https://localhost:8080/admin/api/v0/Contract', json={'firstname' : 'Max', 'lastname' : 'Mustermann', 'street' : 'Dörfelstraße', 'house_number' : '7', 'zip' : '09496', 'city' : 'Marienberg', 'phone' : '037359387570', 'birthday' : '1970-01-01'})
# {"ret":"success","id":500001}
# MODIFY first name of newly created contract
ret = json.loads(r.text)
r = session.patch('https://localhost:8080/admin/api/v0/Contract/{}'.format(ret['id']), json={'firstname' : 'Maxi'})
# {"ret":"success"}
# CREATE a contract with missing birthday -> validation fails
r = session.post('https://localhost:8080/admin/api/v0/Contract', json={'firstname' : 'Missing', 'lastname' : 'Birthday', 'street' : 'Dörfelstraße', 'house_number' : '7', 'zip' : '09496', 'city' : 'Marienberg', 'phone' : '037359387570'}
# {"ret":{"birthday":["The birthday field is required."]}}
# DELETE a contract with a certain id (500001)
r = session.delete('https://localhost:8080/admin/api/v0/Modem/500001')
# {"ret":"success"}
# The same operations are available for all the other database objects as well. e.g.:
# Qos
r = session.get('https://localhost:8080/admin/api/v0/Qos/create')
r = session.post('https://localhost:8080/admin/api/v0/Qos', json={'name' : '1000:100 test', 'ds_rate_max' : '1000', 'us_rate_max' : '100'})
ret = json.loads(r.text)
r = session.patch('https://localhost:8080/admin/api/v0/Qos/{}'.format(ret['id']) json={'name' : '100:10 test', 'ds_rate_max' : '100', 'us_rate_max' : '10'})
r = session.post('https://localhost:8080/admin/api/v0/Qos', json={'name' : 'missing us rate test', 'ds_rate_max' : '1000'})
r = session.delete('https://localhost:8080/admin/api/v0/Modem/{}'.format(ret['id']))
# Modem
r = session.get('https://localhost:8080/admin/api/v0/Modem/create')
r = session.post('https://localhost:8080/admin/api/v0/Modem', json={'mac' : '00:11:22:33:44:55', 'contract_id' : '500000', 'configfile_id' : '3', 'qos_id' : '1'})
ret = json.loads(r.text)
r = session.patch('https://localhost:8080/admin/api/v0/Modem/{}'.format(ret['id']) json={'configfile_id' : '6'})
r = session.delete('https://localhost:8080/admin/api/v0/Modem/{}'.format(ret['id']))
# Mta
r = session.get('https://localhost:8080/admin/api/v0/Mta/create')
r = session.post('https://localhost:8080/admin/api/v0/Mta', json={'mac' : '11:22:33:44:55:66', 'modem_id' : '100000', 'configfile_id' : '186'})
ret = json.loads(r.text)
r = session.patch('https://localhost:8080/admin/api/v0/Mta/{}'.format(ret['id']) json={'configfile_id' : '181'})
r = session.delete('https://localhost:8080/admin/api/v0/Mta/{}'.format(ret['id']))
# Phonenumber
r = session.get('https://localhost:8080/admin/api/v0/Phonenumber/create')
r = session.post('https://localhost:8080/admin/api/v0/Phonenumber', json={'country_code' : '0049', 'prefix_number' : '030', 'number' : '123456', 'mta_id' : '300000', 'port' : '1', 'username' : 'mustermann', 'password' : 'secret', 'sipdomain' : 'sip.provider.com', 'active' : '1'})
ret = json.loads(r.text)
r = session.patch('https://localhost:8080/admin/api/v0/Phonenumber/{}'.format(ret['id']) json={'active' : '0'})
r = session.delete('https://localhost:8080/admin/api/v0/Phonenumber/{}'.format(ret['id']))
print(r.text) |
| Code Block | ||||||||
|---|---|---|---|---|---|---|---|---|
| ||||||||
import json
import requests
session = requests.Session()
session.auth = ('api@localhost', 'secret')
r = session.get('https://localhost:8080/admin/api/v0/Mta/300023/restart')
# {"ret":"success"}
r = session.get('https://localhost:8080/admin/api/v0/Mta/300023/restart')
# {"ret":"Could not restart MTA! (offline?)"}
r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/status')
# {"ret":"success","online":true}
r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/restart')
# {"ret":"Das Modem wurde erfolgreich über das CMTS neugestartet"}
r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/status')
# {"ret":"success","online":false}
r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/restart')
# {"ret":"Das Modem konnte nicht neugestartet werden! (offline?)"}
print(r.text) |
Getting API URLs
In order to modify objects of other types than the ones mentioned above one needs to find the according API URL. This can be accomplished using the WebGUI by clicking on the according object. For example one may want to modify Endpoints. They can be retrieved using the WebGUI by clicking on "Provisioning" → "Endpoints". This leads to the URL https://localhost:8080/admin/Endpoint. Thus the API Base-URL for the endpoints will be: https://localhost:8080/admin/api/v0/Endpoint.