Application Programming Interface (API)

The API section is a comprehensive resource that provides detailed documentation and guidance on utilizing the FileWave API. Whether you're a developer or an IT professional looking to integrate FileWave functionality into your own applications or workflows, this section offers valuable insights. Discover comprehensive API reference documentation, code samples, and tutorials that walk you through the process of leveraging the FileWave API. By leveraging the API, you can automate tasks, streamline workflows, and integrate FileWave functionality seamlessly into your existing systems. Unlock the full potential of FileWave by harnessing the power of the API and customizing your FileWave deployment to suit your specific needs.

What is an API?

What

Application Programming Interface (API).  APIs programmatically provide the reading or writing of information to one or more services.

FileWave has a rich set of APIs to allow customers to build connections. Some vendors also produce integrations, utilising FileWave API, without needing to work with the API directly.

When/Why

APIs extend the capability and integration of FileWave with other Systems. 

How

The articles linked to this article are a good starting point. Professional Services can also help with learning and using APIs.

An important note on URLs

FileWave has 2 APIs

History

For inventory purposes, FileWave has a Command Line API, designed to interact with Inventory Queries.  This API has existed for years and can work on either port 20443 or port 20445.

Since the introduction of the FileWave web admin, 'FileWave Anywhere', a new API was created.  FileWave Anywhere interacts with the FileWave Server using this new API.  Unless configured otherwise, FileWave Anywhere works over port 443.

The Web API has its own paths, when compared with the Command Line version (note the extra /api at the beginning of the path. Below is an example, which creates a new Inventory Query, using both APIs.

TCP port 443 (default port if not specified in URL). Notice that it begins with /api/inv/api/

curl -s -H "Authorization: e2M2sssYjIwLTxxx1hMzdiLTFmyyyGIwYTdjOH0=" https://myserver.filewave.net/api/inv/api/v1/query/ \ 
    --header "Content-Type: application/json" -X POST -d @ios16_incompatible.json

TCP port 20445 (could also use port 20443). Notice that it begins /inv/api/

curl -s -H "Authorization: e2M2sssYjIwLTxxx1hMzdiLTFmyyyGIwYTdjOH0=" https://myserver.filewave.net:20445/inv/api/v1/query/ \ 
    --header "Content-Type: application/json" -X POST -d @ios16_incompatible.json

Since the Web API is used for all server interaction, strictly speaking anything that can be achieved in FileWave Anywhere may also be programmed.  As such, the scope of the Web API is broader in the main than that of the Command Line version.

The Web API has both public and private URLs.  Private URLs can be changed, between FileWave versions, at any time without warning or notification and as such should be avoided in scripts and other systems interacting with FileWave.  They are easily recognisable by the word 'internal' in their URL paths, as per below:

https://${server_dns}/filewave/api/devices/internal/devices/${filewave_id}/details/custom_fields/fields

Working With APIs

Getting Started

The purpose of this guides is two fold:

Command Line API refers to the original RESTful API.  Recognisable both by the port used and URL paths commencing:  

FileWave Anywhere API v2 refers to the newer web admin, FileWave Anywhere, API and recognisable by paths commencing:

Purpose of an API

As described, APIs are designed to communicate with systems.  As such, FileWave may be leveraged by other systems, e.g. SCCM data engines, in-house databases, etc.  To maintain security, there must be an authentication method to allow such communication to take place.  The API provides this kind of ability to provide in-depth integration on an as-needed basis.

Basic, non-specific command line examples:

macOS shell

curl -s -H "Authorization: $auth" \
    https://$server_dns:20445/inv/api/v1/query_result/ \
    --data $query \
    -H "Content-Type: application/json"

Windows PowerShell

$header = @{Authorization=“$auth"}

Invoke-RestMethod -Method POST \ 
    -Headers $header \
    -ContentType application/json \
    -Uri https://$server_dns:20445/inv/api/v1/query_result/ \
    -Body $query

The macOS 'Authorization' or Window's 'Headers' make use of base64 tokens.  From the above code, $auth would need to be set as one of these tokens.

Each user generated will have their own unique base64 token automatically generated.  This token can be revoked and new tokens created.  Each user may have multiple tokens.

The Token is the Key

The token allows access to any API calls from anything that has access to the FileWave Server.  It should not be shared unnecessarily and otherwise should be kept secret.

Tokens may be viewed from FileWave Central App:

Select a desired Administrator and choose the 'Application Tokens' tab.  The token value to copy is the 'Token (base64)'

image.png

Token value from above image:

e2E4YWZkNGFlLTFjZGEtNDVhOC04NTIzLWVhODg1ZWQ3MDg4OH0=

When choosing accounts and tokens for API interaction, consider making dedicated users for the task(s) required.  Set the permissions of that user to limit their ability to the required task alone.  If the token is compromised, this will limit not only the scope of how that token could be used by an attacker, but when revoking and generating a new token, minimal impact would be experienced.

For more information on the Application Tokens see the page: Managing FileWave Administrators (Application Tokens)


API Requests

Requests could be one of:

Command Type Description
GET Returns a resource value
PUT Replaces a resource
PATCH Updates a resource
POST Creates a resource
DELETE Removes a resource

Data sent with requests are in the form of a JSON, as are the responses from those requests.

JSON data is broken into keys/value pairs, where values could even be lists inside of lists.

Examples

Below examples are using a python tool to reformat the returned response.  Python must be installed to benefit from this. If not, remove the piped section of the command or instal Python.

For example, actioning a GET to list of all FileWave Server Inventory Queries, could return a JSON similar to the below:

List Existing Inventory Queries

1) Get all Queries

curl -s  -H "Authorization: e2FjYzRkYmQzLTI3ZjYtNDEyMi1iMGVhLTI1YmY0OGNmYWM0NX0=" \
    https://myserver.company.org:20445/inv/api/v1/query/ | python3 -mjson.tool
[
    {
        "id": 1,
        "name": "All Windows",
        "favorite": true,
        "group": 1,
        "version": 1
    },
    {
        "id": 2,
        "name": "Mac OS X 10.7-10.11",
        "favorite": false,
        "group": 1,
        "version": 5
    },
...
    {
        "id": 103,
        "name": "All Computers to retire",
        "favorite": false,
        "group": 3,
        "version": 2
    }
]
Key Value Description
id integer The unique number for the query. To be used as reference
name string The name given to the query
favorite true/false Whether or not the query should show in the sidebar
group integer The group number given. built-in queries – for example – would be in the "Sample Queries" group, which is group 1. If the user made new groups
version integer The version for the query. How many times has the query been altered and saved, starting with 1
Return the definition of a chosen query

The query definition, not the results of the query.  Using ID 1 as an example:

2) Get Query

curl -s -H "Authorization: e2FjYzRkYmQzLTI3ZjYtNDEyMi1iMGVhLTI1YmY0OGNmYWM0NX0=" \
    https://myserver.company.org:20445/inv/api/v1/query/1 | python3 -mjson.tool
{
    "criteria": {
        "expressions": [
            {
                "column": "type",
                "component": "OperatingSystem",
                "operator": "=",
                "qualifier": "WIN"
            }
        ],
        "logic": "all"
    },
    "favorite": true,
    "fields": [
        {
            "column": "device_name",
            "component": "Client"
        },
        {
            "column": "filewave_client_name",
            "component": "Client"
        },
        {
            "column": "name",
            "component": "OperatingSystem"
        },
        {
            "column": "version",
            "component": "OperatingSystem"
        },
        {
            "column": "build",
            "component": "OperatingSystem"
        },
        {
            "column": "edition",
            "component": "OperatingSystem"
        }
    ],
    "main_component": "Client",
    "name": "All Windows",
    "id": 1,
    "version": 1,
    "group": 1
}

Key Value Description
criteria array Expressions and logic of query

Criteria Expressions (Each entry will require all of the below.  Add multiple entries to the array as required):
Key Value Description
column

Multiple values

e.g. 'version', 'device_id', etc.

Chosen search component 

(Figure 1.2 #1)

component

Multiple values

e.g. 'Client', 'OperatingSystem', etc.

Group containing above component

 (Figure 1.2 #2)

operator

Multiple values

e.g.'is', 'begins', etc.

Method of comparison

(Figure 1.2 #3)

qualifier

Multiple values

(Either a: String, Integer, Date or Boolean value)

Value for comparison

(Figure 1.2 #4)

Logic:

Key Value Description

logic

Multiple values

'all', 'none' or 'one'

How Components should be logically considered for correct return of results

(Figure 1.2 #5)

favourite true/false



Show/Hide from FileWave Central sidebar Inventory Queries
fields array



Which components will be shown (ordered first to last)

Fields to display (Each entry will require all of the below.  Add multiple entries to the array as required):
Key Value Description

column

Multiple values

e.g. 'device_name', 'name', etc.

Component to display

(Figure 1.2 #1)

component

Multiple values

e.g. 'Client', 'OperatingSystem', etc.

Group containing above component

 (Figure 1.2 #2)

main_component Selection Box



Important this is set correctly (Figure 1.2 #6)
name string



Inventory Query name shown in FileWave Central
id integer



Inventory Query unique number, not already in use. 

(Each query has a unique number, starting at 1 and incremented with each new query generated when actioned through FileWave)

version

integer



Increment by 1 for each alteration

group

integer



The Inventory Query group which the query should be displayed within.

E.g. 'group' value of 1 would be within the 'Sample Queries' group

 

image.png

Figure 1.2 - Query Builder Criteria

Return the Inventory Query Results

3) Get Query Results

curl -s  -H "Authorization: e2FjYzRkYmQzLTI3ZjYtNDEyMi1iMGVhLTI1YmY0OGNmYWM0NX0=" \
  https://myserver.company.org:20445/inv/api/v1/query_result/1 \
  | python3 -mjson.tool
{
    "total_results": 13,
    "filter_results": 13,
    "offset": 0,
    "values": [
        [
            "FW-BLUE-02",
            "FW-Blue-02",
            "Windows 10.0",
            "10.0.0",
            "10240",
            "Microsoft Windows 10 Home"
        ],
        [
            "LAPTOP-C6LLFGH6",
            "FH-History3",
            "Windows 10.0",
            "10.0.0",
            "14393",
            "Microsoft Windows 10 Home"
        ],
...
    ],
    "version": 3
}
Key Value Description
total_results integer Total count of results
filter_results integer  
offset integer  
values array The results. Repeated for each result. Items depends on what your specified in the fields
version integer The version for the query. How many times has the query been altered and saved, starting with 1

JSON

Verify JSON Formatting:

API Application 

Browser Extensions

Commands

Remember:  All URLs start with

https://myserver.company.org:20445/inv/api/v1/

Must include the authorization header

Below are the possible options:

URLs

URL Use Options
Inventory
query Show all queries GET POST
query/# Show information on a single query

Where # is the query ID
GET PUT DELETE
query_group/ Show all query group GET POST
query_group/# Detail information on a single group

Where # is the group ID
GET PUT DELETE
query_result/# Show the results of one query

Where # is the query ID
GET POST
query_count   POST
component Show all component options on your instance GET
field_type Show all fields on your instance GET
License
license_definition Show all query GET
license_definition/# Show information on a single license

Where # is the license ID
GET
Custom Fields
custom_field/ Show all custom fields  
custom_field/get_association   POST
custom_field/set_association   POST
custom_field/upload   POST
custom_field/usages/<Field_Name> Where <Field_Name> is the Internal Name (E.G "battery_cycle_count") GET
custom_field/values/   POST
custom_field/edit/   POST

Examples

Using a browser extension

Using Mod-Header (see tools section), you can make Chrome a RESTful API browser by taking advantage of the FileWave Django Framework. Leveraging URLs and authorisation token to return Query Results.

image.png

Even if the URL is typically a POST, it provides an output similar to the following