Rest API for Devices

Owned by Chris Clark
Last updated: Mar 18, 2020 by David McNichol
6 min read

Overview

To allow programmatic access to information on devices in your tenant UDM Pro has a Rest API from v2.1.0 onwards.

The Rest API allows access to the following fields currently, this will expand in future releases. The field name is self-explanatory and can be used to limit the output or used in the search parameter.

  • mac_address (PK)
  • line_registered
  • ip_address
  • location_name
  • sip_address
  • user_contact
  • model
  • software_version
  • note
  • last_seen

If you do not need to pull all the devices we recommended using the take, skip and search parameters to limit the number of devices returned.

Authentication

To gain access to the service an authentication token is used to authorize each request. The below request will generate your authentication token.

POST https://<serverURL>/searchApi/token

You will need to pass a username and password in the POST request body.

POST Body
{"username": "yourUserName", "password":"yourPassword"}

NOTE: You may wish to create a specific user for using with the REST API which only has read access to devices in its role for increased security.

Example Response
{
    "accessToken": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiGfdWRtYWRtaW4iLCJyb2xlcyI6WyJST0xFS0FETUlOIl0sImV4cCI6YTU4NTEzMTI2NCwiaWF0IjoxNTg0NTI2NDY0fQ.RJ2MmrSIifoJTUPy3InMm_z3fAoZibCBVxcSSYA8Zhs",
    "expiration": 604800
}

Requesting Data

Once you have an access token you can then request data using a GET request. Add the access token to your request headers:

Example Request Header
Authorization:Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiGfdWRtYWRtaW4iLCJyb2xlcyI6WyJST0xFS0FETUlOIl0sImV4cCI6YTU4NTEzMTI2NCwiaWF0IjoxNTg0NTI2NDY0fQ.RJ2MmrSIifoJTUPy3InMm_z3fAoZibCBVxcSSYA8Zhs


To retrieve device data use:

GET https://<serverURL>/searchApi/devices

You can also use the following search parameters, if you need to use multiple search parameters use "&" to join them e.g. https://server.com/searchApi/devices?skip=40&take=20

  • format - json (default), csv
  • search (column content) - search=[location_name=HQ, mac_address=000*] * in search is wild card
  • columns - columns=[mac_address,ip_address,model,user_contact] – The MAC address is always returned even if it is not specified in the list of columns.
  • orderBy (column name)
  • take - Take the first xx results returned. Example return the first 10 results; take=10
  • skip - Skip the yy results returned and take the next xx. Example skip the first 40 results and return the next 20; skip=40&take=20


If a search result's JSON property contains no data, the property will not be included in the JSON object.

Examples

IMPORTANT: There is no error checking in the code below and is supplied as is for your reference only.

There are a number of ways you can access the data through the Rest API.

HTTP

GET https://<serverURL>/searchApi/devices?format=csv&search=[location_name=HQ, mac_address=000*]&columns=[mac_address,ip_address,model,user_contact]&orderBy=mac_address&skip=10&take=20

Authorization: Bearer <Auth Token>

PowerShell

# Example script for returning the device

# Display logon dialog to get logon details
# Using a password file and username variable will be best for automating the script

$cred = Get-Credential -Credential $null

# Create logon credentials JSON data structure

$logon = @{
username = $cred.UserName
password = $cred.GetNetworkCredential().Password
}

$JSON = $logon | ConvertTo-Json

# Issue request to get the authorization token

$token = Invoke-RestMethod -Uri "https://<serverURL>/searchApi/token" -Method Post -Body $JSON -ContentType "application/json"

# Create headers with access token for request

$headers = @{
Authorization = 'Bearer {0}' -f $token.accesstoken
Accept = 'application/json'
'Content-Type' = 'application/json'
}

# Issue request for all devices

$Output = Invoke-WebRequest -Uri "https://<serverURL>/searchApi/devices" -Method Get -Headers $headers -ContentType "application/json"

# Other example calls
# To limit the data returned you can use the following format
# $Output = Invoke-WebRequest -Uri "https://<serverURL>/searchApi/devices?columns=[mac_address,ip_address,software_version]" -Method Get -Headers $headers -ContentType "application/json"
#
# Return only VVX300 or VVX301
# $Output = Invoke-WebRequest -Uri "https://<serverURL>/searchApi/devices?search=[model=*VVX_30*]" -Method Get -Headers $headers -ContentType "application/json"
#


# Modify JSON content to readable format

$devices = convertfrom-JSON -inputObject $output.Content

# Display devices returned. Use fl command to see all the fields if some fields are blank

echo $devices | fl


Access API through Excel (PowerBI)

Using the Power Query Editor you need to create a function and then a query. The example below is for Excel but if you are familiar with PowerBI then the process is the same.

IMPORTANT: There is no error checking in the code below and is supplied as is for your reference only.

To start with if you want to manage the values outside of the query then create a Table in Excel like this

For the purpose of the code it will use the table name Rest API Authentication with the fields URL, username and password, you can use your own values but then change the code below. IMPORTANT: Everything is case sensitive.


To get to the Query Editor go to the Data Menu, Get Data, From Other Sources, Blank Query

In query builder go to the advanced editor and paste

let
    FnUDMGetAccessToken =()=>

        let
            // Get url and credentials from config worksheet - Table REST_API_Authentication
            UDMUrlStr = Excel.CurrentWorkbook(){[Name="Rest_API_Authentication"]}[Content]{0}[URL],
            UDMusername = Excel.CurrentWorkbook(){[Name="Rest_API_Authentication"]}[Content]{0}[username],
            UDMpassword = Excel.CurrentWorkbook(){[Name="Rest_API_Authentication"]}[Content]{0}[password],

            UDMcontent = "{
	        	      ""username"":"  & UDMusername & ",
		              ""password"":" & UDMpassword & "
                           }",

            // Calling UDM API Get Access Token
            getAccessTokenUrl = UDMUrlStr & "/searchApi/token", 

            TokenJson = try Json.Document(Web.Contents(getAccessTokenUrl, [Content=Text.ToBinary(UDMcontent)])),

            #"Converted to Table" = Record.ToTable(TokenJson),
            Value = #"Converted to Table"{1}[Value],
            accessTokenStr = Value [accessToken]
        in
            accessTokenStr

in FnUDMGetAccessToken


You should end up with something like this

Next create a query in Query Builder

let
    
    // Get Url from config worksheet - Table REST_API_Authentication
    UDMUrlStr = Excel.CurrentWorkbook(){[Name="Rest_API_Authentication"]}[Content]{0}[URL],


    // Build UDM Device API URL
    getDeviceUrl = UDMUrlStr & "/searchApi/devices",
   
    // Get Access Token URL parameter
    accessTokenParamStr = FnUDMGetAccessToken(),
 
        
    // Send REST API Request             
    content = Json.Document(Web.Contents(getDeviceUrl, [Headers=[#"Authorization"="Bearer " & accessTokenParamStr]])),
    #"Converted to Table" = Table.FromList(content, Splitter.SplitByNothing(), null, null, ExtraValues.Error),
    #"Expanded Column1" = Table.ExpandRecordColumn(#"Converted to Table", "Column1", {"mac_address", "line_registered", "ip_address", "location_name", "sip_address", "model", "software_version", "last_seen", "note"}, {"Column1.mac_address", "Column1.line_registered", "Column1.ip_address", "Column1.location_name", "Column1.sip_address", "Column1.model", "Column1.software_version", "Column1.last_seen", "Column1.note"}),
    #"Reordered Columns" = Table.ReorderColumns(#"Expanded Column1",{"Column1.mac_address", "Column1.sip_address", "Column1.ip_address", "Column1.model", "Column1.location_name", "Column1.software_version", "Column1.note", "Column1.line_registered", "Column1.last_seen"}),
    #"Renamed Columns" = Table.RenameColumns(#"Reordered Columns",{{"Column1.mac_address", "Mac Address"}, {"Column1.sip_address", "Sip Address"}, {"Column1.ip_address", "IP Address"}, {"Column1.model", "Model"}, {"Column1.location_name", "Location"}, {"Column1.software_version", "Software Vers"}, {"Column1.note", "Notes"}, {"Column1.line_registered", "Line Registered"}, {"Column1.last_seen", "Last Seen"}})
in
    #"Renamed Columns"


You will then end up with this.


When you click Close and Load in Query Builder it will take you back to Excel and populate a sheet with all the values returned.