File Director REST API

File Director (2020.3 and later) now supports a REST API. This enables administrators with required coding skills to develop their own scripts and automate appliance management tasks.

The API use-case described is for upgrading an appliance or a cluster of appliances.

Note, unless otherwise stated, all APIs return body in JSON format.

Authentication

[POST /auth/logon]

Endpoint

Description
[POST /auth/logon]

REST API is using JWT tokens to authenticate requests. Each API endpoint returns 401 http error code unless a valid token is provided in the 'Authorization' header.

The token can be obtained with the /auth/logon API.
Parameters (multipart/form-data) username - username used for logon (can be 'appliance' user or any user defined as Administrator) [required]

password - corresponding password [required]

Response examples

HTTP code

HTTP body

Details

401

 No payload Bad credentials. Valid credentials need to be sent to authenticate the user.

200

 {"token":"eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2MDI4NDY4NzgsImlhdCI6MTYwMjg0MzI3OCwia
XNzIjoiZmlsZWRpcmVjdG9yLml2YW50aS5jb20iLCJyb2xlcyI6WyJzdGF0dXMiLCJjb25maWciL
CJwb2xpY3kiXSwidXNlciI6eyJ1c2VybmFtZSI6IkFkbWluaXN0cmF0b3IifX0.zVJZiNkoxRBJOuBM
tnydZbAmm4yhQaSPwrdAx1jcB0"}		 Returns an auth token that should be sent with any future request (in 'Authorization' header)

400

 { "error": "Error, Missing username and/or password" } Request needs to include all the required parameters

API Navigation

[GET /products]

Endpoint

Description
[GET /products]

Returns a list of products that can be managed using REST API.

Response examples

HTTP code

HTTP body

Details

200

 [{"name":"platform"},{"name":"filedirector"}] Use the returned data to navigate the REST API endpoints

[GET /products/filedirector]

Item

Description
[GET /products/filedirector]

Returns a list of high level API endpoints available for "File Director" product.

Response examples

HTTP code

HTTP body

Details

200

 {"name":"services"} Use the returned data to navigate the REST API endpoints

[GET /products/platform]

Endpoint

Description
[GET /products/platform]

Returns a list of high level API endpoints available for "Platform" product.

Response examples

HTTP code

HTTP body

Details

200

 {"name":"services"} Use the returned data to navigate the REST API endpoints

[GET /products/filedirector/services]

Endpoint

Information
[GET /products/filedirector/services]

Returns a list of "File Director" services that can be managed by REST API.

Response examples

HTTP code

HTTP body

Details

200

 [] Use the returned data to navigate the REST API endpoints

[GET /products/platform/services]

Endpoint

Information
[GET /products/platform/services]

Returns a list of "Platform" services that can be managed by REST API.

Response examples

HTTP code

HTTP body

Details

200

 {"name":"patch"} Use the returned data to navigate the REST API endpoints

Platform: patch service

Patch service is used to apply File Director appliance updates provided by Ivanti. Both standalone (single node) and cluster deployments can be updated. In a case of a cluster, make sure one of its nodes is marked as a patch server.

A recommended workflow for update script is as follows:

  1. Obtain authentication token with [POST /auth/logon]

  2. Upload the update file (obtained from Ivanti) with [POST /products/platform/services/patch]

  3. Wait until the update is staged to each of the nodes. This can be checked by periodically calling the [GET /products/platform/services/patch] API and checking the 'patching_status'. The status should have a value of "staged" for each of the nodes in 'patching_status' hash.

  4. Start the patching process with [POST /products/platform/services/patch/apply].

  5. Wait until the patching process is complete. This can be checked by periodically calling the [GET /products/platform/services/patch] api and checking the 'patching_status'. The status should have a value of "no updates" for each of the nodes in 'patching_status' hash. This can take some time, depending on the nature of the update. During this process nodes get rebooted so the script needs to be able to handle connection exceptions.

[GET /products/platform/services/patch]

Endpoint

Information
[GET /products/platform/services/patch]

Gets details about the currently staged patch. Returns a list of nodes and their patching status as well as update details.

Response examples

HTTP code

HTTP body

Details

200

 {"patching_status":{"192.168.225.11":{"status":"no updates"}},"update_details":null} No patch is currently staged for update.

200

{"patching_status":{"192.168.225.11":{"status":"staged"}},"update_details":{"components":[{"revision":"4.100.0.0","product":"Appliance Configuration Services","c":"(c)2020","kind":"release","id":"config"}],"name":"File Director 2020.3","description":"more details"}}

Patch is uploaded (staged) and ready to be applied. Details about the patch and the patching status are returned. "patching_status" is a hash where a key is an IP address of the node in the cluster and value include patching status for that node. Value of "status" can be:

"staged" - if patch is uploaded and the node is ready to apply it

"no updates" - if no patch is present

 

[POST /products/platform/services/patch]

Endpoint

Information
[POST /products/platform/services/patch]

Upload a new patch. Patch is automatically copied and staged on each node in the cluster so that it is ready to be applied. In a clustered scenario it may take some time for all the nodes to be ready, current state can be monitored with GET /products/platform/services/patch API.
Parameters (multipart/form-data)

update - uploaded patch file content

Response examples

HTTP code

HTTP body

Details

202

 no body Patch has been uploaded successfully.

400

no body

Invalid patch file has been uploaded.

 

[DELETE /products/platform/services/patch]

Endpoint

Information
[DELETE/products/platform/services/patch]

Remove the currently staged patch.

Response examples

HTTP code

HTTP body

Details

204

 no body Currently staged patch has been removed.

 

[POST /products/platform/services/patch/apply]

Endpoint

Information
[POST /products/platform/services/patch/apply]

Applies the currently staged patch.

Response examples

HTTP code

HTTP body

Details

202

 no body Starts the patching process.

500

no body

Nodes are not ready to be patched.

 

[GET /products/platform/services/patch/history]

Endpoint

Information
[GET /products/platform/services/patch/history]

Get a history of applied patches.

Response examples

HTTP code

HTTP body

Details

200

 [{"time":"2020-10-15 11:14:59 UTC","session":[{"kind":"release","c":"(c) 2020", "id":"config", "product":"Appliance Configuration Services", "revision":"4.100.0.0", "feature_id":"appliance"}, ...],"seconds_ago":8742}, ...] Each item in the array includes details about one patching session and its time. Each session contains a list of components that were updated.

 

[GET /products/platform/services/patch/current]

Endpoint

Information
[GET /products/platform/services/patch/current]

Get details about the current appliance components versions.

Response examples

HTTP code

HTTP body

Details

200

 {"revision":"4.8.0.1","product":"appliance","c":"(c) 2020", "kind":"release", "id":"appliance", "marketing_version":"File Director 2020.2", "components":[ {"revision":"4.100.0.0","product":"Appliance Configuration Services", "c":"(c) 2020", "kind":"release", "id":"config"},{"revision":"4.11.0.1","product":"Appliance Text Console", "c":"(c) 2020","kind":"release","id":"aci"}, {"product":"Appliance Operating System","c":"(c) 2020","kind":"release","id":"os","revision":"20201015"}, {"product":"Fission Clustering Services","c":"(c) 2020","kind":"release","id":"fission","revision":"4.11.0.66"}, {"revision":"4.6.0.1","product":"Patch Server","c":"(c) 2018","kind":"release","id":"patch_server"}, {"product":"File Director Server","c":"(c) 2020","kind":"release","id":"datanow","revision":"4.11.0.156"}, {"product":"File Director Web Admin","c":"(C) 2020","kind":"release","id":"datanow_admin","revision":"4.11.0.52"}, {"product":"File Director Web Client","c":"(c) 2020","kind":"release","id":"datanow_webclient","revision":"4.11.0.19"}, {"revision":"4.11.0.5","product":"File Director Appliance Plugins","c":"(c) 2020","kind":"release","id":"acs_datanow"}]} Includes version information about currently installed components.