One of the key features of the 8.1 release of EFT was the upgrade from a 32bit application to a 64bit application; however, another feature that arrived in the same version is often overlooked – the expansion of the REST API functionality. REST (or REpresentational State Transfer) has quickly become the standard to allow disparate systems to talk to one another, rather than relying on older methods such as SOAP. More importantly for system administrators, most applications now come with a REST API which can be used to manage their systems.

An introduction to REST API

EFT has had an underused REST API for a number of years – it was added as a means of allowing EFT Insight to talk back to the EFT system – but until recently only provided some low-level password reset functionality for end users.

Expanding the REST API functionality in EFT means you no longer have to use the COM API for automated management tasks. This is a benefit as a remotely installed COM API-enabled client would require certain DLLs to be copied locally and registered; in REST there is no need for this as you simply need to connect to EFT over HTTPS in order to access the API.

Calls to the REST API are frequently made through scripts; my preference for scripting is powershell, hence my examples below are set up that way. REST API calls generally return results in JSON format; powershell handles this format very well.

Getting started with REST API

In any script connecting to EFT, the first few lines are always going to be the same. Don’t be afraid to plagiarise or reuse code at this point. I like to start off by declaring the URL, admin user and password of my EFT. Be sure to check in EFT that the admin user has the right to use REST; the URL will simply be the DNS or name of your EFT server, connecting on port 4450 by default. In my script below, these are the only things that will need to be changed. After you set these variables, we can create an authentication header that we can use in our API calls.

Sample Script

This script lists all of the folders in the VFS on each site. Although I’ve not included it, it would not be too difficult to get the permissions for each folder listed – we routinely get asked for this.

At the top of the script, I have added a function. It’s good practice to define functions before anything else in powershell. This function simply takes a folder name as input and lists its subfolders, then calls the same function for each subfolder. You’ll notice that I am building a full folder path in this process and wrapping the folders with “%2F”. This is because you cannot pass a slash character into the REST API call without first encoding it for accessibility. I also URL encode the subfolder name in case of non-compliant characters.

function VFSSubs($vfsfolder) {

       $subs = Invoke-RestMethod -Uri "$EFTURL/v2/sites/$sid/filesystem/folders/%2F$vfsfolder%2F" -Method 'GET' -Headers $authHeader

       foreach ($sub in $subs.data.attributes.subfolders) {

             $subname = [System.Web.HttpUtility]::UrlEncode($vfsfolder + "/" + $sub)

             $subname

             VFSSubs($subname)

       }

}

Once the function is declared, I define the variables that I mentioned earlier

$EFTURL = "https://MYURL:4450/admin"

$EFTAdm = "MY_API_USER"

$AdmPass = "MY_API_USER_PASSWORD"

This next line is only required in the event of the URL not being protected by a correct certificate (i.e. self signed, I.P. address etc). The $EFTURL variable will form the stem for all subsequent URLs that we call.

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

I then go on to build the authentication header:

$authBody = "{""userName"": ""$EFTAdm"", ""password"": ""$AdmPass"", ""authType"": ""EFT""}"

$auth = Invoke-RestMethod -Uri "$EFTURL/v1/authentication" -Method 'POST' -Body $authBody

$authToken = $auth.authToken

$authHeader = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

$authHeader.Add("Authorization", "EFTAdminAuthToken $authToken")

Once you have the authentication header, it’s a simple case of listing the sites on the EFT server and looping through them.

$sites = Invoke-RestMethod -Uri "$EFTURL/v2/sites" -Method 'GET' -Headers $authHeader

foreach ($site in $sites.data)

{

       $sid = $site.id

       $sitename = $($site.attributes.name)

       "=== Listing VFS for $Sitename ==="

Inside the site loop, we list out the top level folder and retrieve their subfolders. Each of these is passed to the function at the top of the script.

       $folders = Invoke-RestMethod -Uri "$EFTURL/v2/sites/$sid/filesystem/folders" -Method 'GET' -Headers $authHeader

       foreach ($folder in $folders)

       {foreach ($subfolder in $folder.data.attributes.subfolders) {VFSSubs($subfolder)}}

}

And that’s it! REST API calls can be quite daunting sometimes, but this is fairly straightforward. Other REST calls can be simply added to retrieve permissions for each folder and the details of the users to whom those permissions have been awarded.

Finally, the REST API script is not limited to read-only – you can easily create, modify or delete items in EFT using the REST API – this includes users, folders, event rules etc.

Check out more benefits of EFT 8.1 here. For support in upgrading to the latest version of EFT, our experts are just a call away, please get in touch with us here.