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.