Introducing the Web API V2

Contents

Introducing the Web API V2

The Web API V2 is an HTTPS service that you invoke by issuing a POST or GET HTTP request to the Engine via the URL:

https://<Engine IP address or DNS name>:<Web API port number>/2/query

The service consists in answering NXQL queries to the in-memory Engine database with a list of records in the selected output format. By default, the Web API port number is 1671.

A request expects the following parameters:

query
The NXQL query to execute.
platform
Specifies the target platform of the query. Should the query target multiple platforms, supply the argument for as many platforms as required. Supported platforms are windows, mac_os and mobile.
format
The expected output format. Available formats are csv, html, xml and json.
hr
Optional: Boolean value that indicates whether the output should be human readable. When true, numerical values in the response are adapted to their best fitting units for better readability. The chosen units are also displayed along with the values. Not used in the JSON output format.

For instance, the request

https://192.168.2.3:1671/2/query?platform=windows&platform=mac_os&query=(select (id name) (from device))&format=csv

returns the list of identifiers and names of all Windows and Mac OS devices in CSV format. Note that the URL encoding of the actual parameters has been omitted for clarity.

Template Parameters

Extra parameters p1, p2, etc. can be added to the query to replace placeholders %1, %2, etc. in the NXQL query. Use placeholders in place of the names of custom fields, names of categories or literal values for parametrizing queries that are used often.

https://<engine>:1671/2/query?query=(select (name #%1) (from device))&p1=Location&format=csv

Authentication

Any account with Data Privacy set to none (full access) and the option Finder access enabled can make use of the Web API. However only those with the right to edit categories can perform updates.

User credentials are verified with basic HTTP authentication. For a given user, the visibility and info levels are identical to those defined in their profile in the Portal.

HTTP Status Codes

The Web API V2 returns:

  • 200 OK: If the request is successful;
  • 400 Bad Request: If the request is invalid;
  • 401 Not Authorized: If no credentials are provided or if they are not valid;
  • 403 forbidden: If Web API is not licensed.

Testing the Web API V2 with the NXQL editor

The NXQL editor is a web-based user interface to the Web API V2. This useful editor lets you test the queries that you will later use in your integration projects. The NXQL editor is present in every Engine with the Integration tookit and you can access it from your favorite web browser by typing in the following URL:

https://<Engine IP address or DNS name>:<Web API port number>/2/editor/nxql_editor.html

To write a query in the NXQL editor:

  1. Provide the user credentials. Type in the user name and password in the two text input boxes at the top. The access rights of the user associated to the supplied credentials apply to the query.
  2. Select the platforms that your query targets by ticking the appropriate platform icons at the top right corner.
  3. Type in your NXQL query inside the big text region in the middle.
    • If your query includes any placeholder for template parameters, specify the value of the parameters in the two text boxes below the query. Editor queries may include up to two template parameters.
  4. Optional: Tick Formatted to get a human readable output (see hr parameter of Web API V2 requests above).
  5. Click Send.

EditorNXQL.png

Once you send your query, the editor displays the message Loading... while the Engine is processing it. After a few seconds, depending on the speed of your connection, the complexity of your query and the load on the Engine, the response appears below the Send button in the same page of the NXQL editor:

EditorOutputNXQL.png

  • Choose the maximum number of displayed rows with the Show x entries picker.
  • Navigate through the result pages with the help of the buttons at the bottom right.
  • Order the results by column in ascending or descending order by repeatedly clicking the title of the column.
  • Click the Other formats options at the bottom left to get the results in CSV, HTML, XML or JSON format.

Using the Web API V2 with wget

The Web API V2 can easily be invoked using the classic UNIX tool wget. For instance, to retrieve the names of all devices in CSV format using wget, write the following command:

> wget --quiet \
  --no-check-certificate \
  --user=admin --password=admin \
  --output-document devices.csv \
  'https://our-engine-dns-name:1671/2/query?
   query=(select%20(id%20name)(from%20device))%20&
   format=csv&
   platform=windows&platform=mac_os'

Using the Web API V2 with PowerShell

The Web API can be invoked using Windows PowerShell, however, since the standard Invoke-WebRequest CmdLet does not support self-signed certificate, you should use the CmdLet defined in the downloadable file Code-For-Invoke-Nxql.ps1. After saving this script, load it into your PowerShell environment. Make sure that your PowerShell execution policy is set to ‘’‘unrestricted

To load the script, type in the following in the PowerShell console:

. ./Code-For-Invoke-Nxql.ps1


To retrieve the list of names of all the devices of any platform in CSV format, for example, execute the following command:

Invoke-Nxql -ServerName 192.168.2.3
  -UserName admin -UserPassword admin
  -Platform windows,mac_os
  -Query "(select (name) (from device))" > devices.csv


To get the full command line options, type in:

Invoke-Nxql -?


Related concepts