Administration with REST API - AdminAPI

CompleteFTP Enterprise MFT's AdminAPI is a REST API for performing administration tasks.

Accessing the AdminAPI

The AdminAPI is disabled by default for security reasons. It can be enabled by enabling the AdminAPI web feature:

Open CompleteFTP Manager
Open the Sites panel
Make sure Show system users/folders/sites is checked in the Options menu at the bottom left
Select the Admin site
Open Advanced HTTP/HTTPS Settings
Select Web features
Click the ellipsis (…) at the right
Check the enabled checkbox next to AdminAPI
Click Close and Apply changes

Only accounts that are members of the admins group are able to access the AdminAPI. However, it's recommended to use an account other than the admin account, so that there's minimal disruption if it becomes necessary to remove access. It's therefore best to create a new admin account and use it only for this purpose. If specific IP filtering rules or network interfaces are to be used for AdminAPI access then a new site could be added, specifically for this purpose.

Authentication for the AdminAPI may be done with HTTP Basic Authentcation using the user-name and password of the admin account created for this purpose (as described in the above paragraph). This authentication method is supported by most HTTP clients. For example, in curl, the -u option may be used to include the appropriate authentication information. For example, the following command will return a JSON object describing the account with user-name, myuser, using the admin account named, myadmin:

curl -u myadmin:mypassword https://myserver:14985/Admin/API/config/users/myuser

Note that, by default, curl validates the server's certificate against the Windows certificate store. This can be disabled with the -k argument, otherwise the certifcate must either be a CA certificate or, if it's a self-signed certificate (the default) then it must be installed in the certificate store.

When starting out with the AdminAPI, it's a good idea to start by accessing it from the same machine on which CompleteFTP is installed. Once you've established that Admin API is working in the way that you need when accessed from localhost, you can try to access it from another machine. By default, CompleteFTP blocks access to administration features from machines that are not on the same LAN, so the admin site's IP filters will need to be modified if such access is required.

Using the AdminAPI

AdminAPI is a REST API, meaning that each operation is executed by sending an HTTPS request to CompleteFTP. Each request is either a HTTP GET or a HTTP POST. The latter request requires a body containing JSON. All requests return a JSON object with the following properties:

success (boolean): either true or false
message (string): ok if the call was successful, otherwise an error-message
apiVersion (string): version of the API (currently 1.0.0)
type (string): type of return value (e.g. Folder, FolderManager, Array, number)
value (specified by type field): return value of API call

The base path is /Admin/API, although can be changed by editing the Admin API web feature. This version of the AdminAPI can only be used for performing configuration actions. These are done via the sub-path, config, so the path of all requests will start with /Admin/API/config. The default HTTPS port for the admin site is 14,985.

URLs for AdminAPI requests take the following form (in WSN):

https://hostname:14985/Admin/API/config/OBJECT[/METHOD[/ARGUMENTS]]

where OBJECT specifies an object such as a user, a group or a folder; METHOD (optional) is the name of a method of the specified object; and ARGUMENTS (optional) is one or more arguments (separated by /) passed to the method.

Retrieving Objects

If an HTTP GET request is sent without specifying a method then the object is returned. For example, sending an HTTP GET request to https://myserver:14985/Admin/API/config/users/MyUser is the URL of the object representing the user, MyUser. It will return a JSON string representing this user:

{
	"success": true;
	"message": "ok",
	"apiVersion": "1.0.0",
	"uri": "https://myserver:14985/Admin/API/config/users/MyUser",
	"type", "User",
	"value": {
		"type": "Non-Windows",
		"inbuilt": false,
		"userName": "MyUser",
		"fullName": "My User",
		"description": "A user intended for testing.",
		"email": "myuser@test.com",
		"siteMapping": [{
			"siteName": "Default Site",
			"enabled": true,
			"homeFolder": "/Home/MyUser"
		},{
			"siteName": "Admin",
			"enabled": false,
			"homeFolder": null
		}],
		...
	}
}

Setting object properties

Properties can be set by sending an HTTP POST to the same URL with either of the two following JSON strings:

{
	"fullName": "My test user"
}

{
	"properties": {
		"fullName": "My test user"
	}
}

Invoking Methods

A method of an object may be invoked by placing its name after that of the object in the URL. If a method takes arguments then those may either be supplied in the URL itself or in the body of the request.

For example, a user may be deleted with the URL, https://myserver:14985/Admin/API/config/users/remove/MyUser. Alternatively, arguments for the method may also be passed to, https://myserver:14985/Admin/API/config/users/remove, via JSON, as follows:

{
	"arguments": [
		"MyUser"
	]
}

While a user can be added with the URL, https://myserver:14985/Admin/API/config/users/add/non-windows, one would usually want to set a some properties of the new user. This may be done by posting the following JSON with the request:

{
	"userName": "MyUser"
}

If the arguments of a method are too complex to be placed in the URL and properties need to be set then a JSON object containing both an arguments field and a properties field. For example, to add a user and set the userName property, the following JSON would be posted to https://myserver:14985/Admin/API/config/users/add:

{
	"arguments": [
		"MyUser"
	],
	"properties": {
		"userName": "MyUser"
	}
}

Available Configuration Objects

The following configuration objects are available:

/Admin/API/config/folders: A JSON array containing the full paths of all folders in the virtual file-system.
/Admin/API/config/folders/FOLDER_NAME{/FOLDER_NAME}: A JSON object containing all properties of the specified folder. The returned object has the same properties and methods as the JSS Folder Object.
/Admin/API/config/users: A JSON array containing the user-names of all users.
/Admin/API/config/users/USER_NAME: A JSON object containing all properties of the specified user. The returned object has the same properties and methods as the JSS User Object.
/Admin/API/config/groups: A JSON array containing the names of all groups.
/Admin/API/config/groups/GROUP_NAME: A JSON object containing all properties of the specified group. The returned object has the same properties and methods as the JSS Group Object.
/Admin/API/config/sites: A JSON array containing the names of all sites.
/Admin/API/config/sites/SITE_NAME: A JSON object containing all the properties of the site. Note that spaces may be omitted, so Default Site is the same as DefaultSite. The returned object has the same properties and methods as the JSS Site Object.

Examples

The examples below demonstrate how to use the Admin API to perform a range of operations. Each example includes curl commands for both Windows and Bash consoles. The commands differ because quotes are handled differently on the two consoles.

Add a user:

URL:

https://localhost:14985/Admin/API/config/users/add

JSON:

{
	"userName":"fred",
	"password":"Fred123"
}

Command (Windows):

curl -u username:password --data "{""userName"":""fred"",""password"":""Fred123""}" https://localhost:14985/Admin/API/config/users/add

Command (Bash):

curl -u username:password --data '{"userName":"fred","password":"Fred123"}' https://localhost:14985/Admin/API/config/users/add

Set user's home folder:

URL:

https://localhost:14985/Admin/API/config/users/fred/siteMapping/DefaultSite

JSON:

{
	"homeFolder":"/Home/fred"
}

Command (Windows):

curl -u username:password --data "{""homeFolder"":""/Home/fred""}" https://localhost:14985/Admin/API/config/users/fred/siteMapping/DefaultSite

Command (Bash):

curl -u username:password --data '{"homeFolder":"/Home/fred"}' https://localhost:14985/Admin/API/config/users/fred/siteMapping/DefaultSite

Get user data:

URL:

https://localhost:14985/Admin/API/users/fred

JSON:

none

Command (Windows):

curl -u username:password https://localhost:14985/Admin/API/config/users/fred

Command (Bash):

curl -u username:password https://localhost:14985/Admin/API/config/users/fred

Disable FTP for user:

URL:

https://localhost:14985/Admin/API/config/users/fred

JSON:

{
	"ftpEnabled":false
}

Command (Windows):

curl -u username:password --data "{""ftpEnabled"":false}" https://localhost:14985/Admin/API/config/users/fred

Command (Bash):

curl -u username:password --data '{"ftpEnabled":false}' https://localhost:14985/Admin/API/config/users/fred

Add a folder:

URL:

https://localhost:14985/Admin/API/config/folders/add

JSON:

{
	"arguments": [
		"/Home/fred",
		"WindowsFolder",
		"C:\\Temp"
	]
}

Command (Windows):

curl -u username:password --data "{""arguments"":[""/Home/fred"",""WindowsFolder"",""C:\\Temp""]}" https://localhost:14985/Admin/API/config/folders/add

Command (Bash):

curl -u username:password --data '{"arguments":["/Home/fred","WindowsFolder","C:\\Temp"]}' https://localhost:14985/Admin/API/config/folders/add

Get folder data:

URL:

https://localhost:14985/Admin/API/config/folders/Home/fred

JSON:

none

Command (Windows):

curl -u username:password https://localhost:14985/Admin/API/config/folders/Home/fred

Command (Bash):

curl -u username:password https://localhost:14985/Admin/API/config/folders/Home/fred

Set folder mapping path:

URL:

https://localhost:14985/Admin/API/config/folders/Home/fred

JSON:

{
	"mappingPath" : "C:\\Temp\Downloads"
}

Command (Windows):

curl -u username:password --data "{""mappingPath"":""C:\\Temp\\Downloads""}" https://localhost:14985/Admin/API/config/folders/Home/fred

Command (Bash):

curl -u username:password --data '{"mappingPath":"C:\\Temp\\Downloads"}' https://localhost:14985/Admin/API/config/folders/Home/fred

Set owner of folder:

URL:

https://localhost:14985/Admin/API/config/folders/Home/fred/access/owner

JSON:

{
	"userName": "fred"
}

Command (Windows):

curl -u username:password --data "{""userName"":""fred""}" https://localhost:14985/Admin/API/config/folders/Home/fred/access/owner

Command (Bash):

curl -u username:password --data '{"userName":"fred"}' https://localhost:14985/Admin/API/config/folders/Home/fred/access/owner