1.1. 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.
See OpenAPI for a full API description: https://www.nmsprime.com/api/
| Drawio | ||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
| Info |
|---|
Please use the email address as username, when trying to authenticate with the API. The password is the same you use to login to the NMS Prime web interface. |
1.2. Inspecting database objects
1.2.1.1.1. Inspecting Qos objects using curl
| Code Block |
|---|
|
| |
# GET all Qos objects |
(in |
this |
case id 1 and 6) $ curl -u api@localhost:secret https://localhost:8080/admin/api/v0/Qos |
{"models":{"1":{"id":1,"created_at":" |
2016- |
09- |
08 |
10: |
38: |
15","updated_at":" |
2020- |
04-10 15 |
: |
57: |
34","deleted_at":null,"ds_rate_max": |
2,"us_rate_max": |
1,"ds_rate_max_help": |
2000000,"us_rate_max_help": |
1000000,"name":" |
2:1","ds_name":"D2M","us_name":"U1M"},"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": |
50000000,"us_rate_max_help": |
2000000,"name":" |
50:2" |
, |
" |
ds_name": |
"D50M"," |
us_ |
name":" |
U2M"}},"success":true} # GET Qos object with a certain id (6) $ curl -u api@localhost:secret https://localhost:8080/admin/api/v0/Qos/6 {"models":{"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": |
50000000,"us_rate_max_help": |
2000000,"name":"50 |
:2" |
, |
"ds_name":" |
D50M"," |
us_ |
name":" |
U2M"}},"success":true,"id":6} |
| Info |
|---|
You need to add verify=False in the get/post/patch statements, if you haven't set up a proper TLS certificate yet. You may do so using Getting a X.509 certificate via Let's Encrypt |
1.2.1.1.2. Inspecting database objects using python
| 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) |
1.3. Creating, modifying and deleting database objects
1.3.1.1.1. Creating database objects using python
| 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={'number' : '0123456789', 'firstname' : 'Max', 'lastname' : 'Mustermann', 'street' : 'Dörfelstraße', 'house_number' : '7', 'zip' : '09496', 'city' : 'Marienberg', 'phone' : '037359387570', 'birthday' : '1970-01-01'}) # {" |
success": |
true,"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'}) # {" |
success":true," |
id":500001} # CREATE a contract with missing birthday -> validation fails r = session.post('https://localhost:8080/admin/api/v0/Contract', json={'number' : '0123456789', 'firstname' : 'Missing', 'lastname' : 'Birthday', 'street' : 'Dörfelstraße', 'house_number' : '7', 'zip' : '09496', 'city' : 'Marienberg', 'phone' : '037359387570'}) # {" |
validations":{"birthday":["The birthday field is required."]},"success":false} # DELETE a contract with a certain id (500001) r = session.delete('https://localhost:8080/admin/api/v0/ |
Contract/500001') # {" |
success": |
true} # 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) |
1.3.1.1.2. Restarting modems/MTAs and getting the online status of a modem
| 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')
# {" |
success":true," |
id":300023} r = session.get('https://localhost:8080/admin/api/v0/Mta/300023/restart') # {"messages":{" |
errors":["Could not restart MTA! (offline?)"]},"success":true,"id":300023} |
r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/status')
# {" |
success": |
true," |
id": |
100003} r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/restart') # {"messages":{" |
infos":["Das Modem wurde erfolgreich |
\u00fcber das |
NetGw neu gestartet"]},"success":true,"id":100003} r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/status') # {" |
success": |
false," |
id": |
100003} r = session.get('https://localhost:8080/admin/api/v0/Modem/100003/restart') # { |
"messages":{"errors":["Das Modem konnte nicht neu |
gestartet werden! (offline?)"]},"success":true,"id":100003} print(r.text) |
1.4. 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.
1.4.1. Postman API Demo Collection:
Set the variable "base_url" for the collection and enter your credentials (email and password) into Basic Auth fields.
or import the json from here:
| View file | ||
|---|---|---|
|