I didn’t know much about the Nextcloud API and despite the documentation being somehow fragmented, the interaction seemed possible using the BaseElements plugin.
The idea is the same: we want to share a folder or file in Nextcloud from within a FileMaker solution.
Nextcloud has more than one API (with different implementations) and for our project we’ll need 3 different services:
- the webDAV API to find files and folders
- the Provisioning API to manage the users
- the Share API to share the files and folders
First of all the format used for the response is not JSON but XML and in the case of the webDAV API we have to define a cURL option to retrieve the field list.
The Nextcloud API provides only Basic Auth without any API keys or Token. We simply pass our username and password with the request:
Get the Files and Folders List
The first step in the process is to retrieve the list of files and folders hosted in our account. For this we’ll use the webDAV API.
The docs indicate that we need to perform a
PROFIND request: to do the we need to set a cURL option before calling our GET request.
The option to set is called
CURLOPT_CUSTOMREQUEST and we have to set it to the value
PROPFIND. The BaseElements plugin function to do this is
BE_Curl_Set_Option ( "CURLOPT_CUSTOMREQUEST" ; "PROPFIND" )
one thing to remember is that the effects of BE_Curl_Set_Option don’t reset after a call. We need to explicitly reset it calling the function without parameters when we don’t need the option anymore.
Once the cURL option is set we can perform our GET request. The url will be our base URL followed by
/remote.php/dav/files/USERNAME/. If our username is
admin and our domain is
goyafm the url will be
or if we want to get the list from a subfolder instead than from the root
We will perform the call using the BE_HTTP_GET function
BE_HTTP_GET ( "https://admin:firstname.lastname@example.org/goyafm/remote.php/dav/files/USERNAME/" )
Get the Users List
To decide who we are sharing our files with we need a way to identify them in the request, so our second step is to retrieve the list of users from the Nextcloud installation.
The Provision API uses a normal HTTP GET request to return an XML message. The HTTP Header OCS-APIRequest needs to be set to "true" and we can use BE_HTTP_Set_Custom_Header to set it
BE_HTTP_Set_Custom_Header ( "OCS-APIRequest" ; "true" ).
The url of the GET request will be our base URL followed by
/ocs/v1.php/cloud/users which using the same example values becomes
BE_HTTP_GET ( "https://admin:email@example.com/goyafm/ocs/v1.php/cloud/users" ) which for the users in this screenshot
<ocs> <meta> <statuscode>100</statuscode> <status>ok</status> </meta> <data> <users> <element>admin</element> <element>nick</element> <element>salvatore</element> </users> </data> </ocs>
Now we have the folder we want to share and the user identification. We can use the Share API to send a POST request to Nextcloud.
If you have used Dropbox, Box or similar in the past the terminology used in Nextcloud can be a bit confusing: every time we share a file or folder we create a new "share", which doesn't mean we are creating a new folder.
So to create a new share we can use the endpoint
/ocs/v1.php/apps/files_sharing/api/v1/shares passing 3 parameters:
- the path of the file to share
- the share type (0 = user; 1 = group; 3 = public link; 6 = federated cloud share)
- the user with which the file should be shared.
These parameters are passed as the body of the POST request. If we want to share the folder
Photos with the user
salvatore the body will be
so the complete request using BE_HTTP_POST will be
BE_HTTP_POST ( "https://admin:firstname.lastname@example.org/goyafm/ocs/v1.php/apps/files_sharing/api/v1/shares" ; "path=/Photos/&shareType=0&&shareWith=salvatore" )
If BE_HTTP_Response_Code returns 200, we know the share was created.
This API was certainly different from the ones we covered in the past and it gave us a way of looking at different functions and different implementations.
A full example file has been added to the shared folder for our sponsors.
If any other subscriber has a request for an API integration, send us your idea!
Salvatore is our web services and integration expert, passionate about linking any API useful to our clients (or us!) to FileMaker. He loves to share ideas and a good story, and as a speaker at DevCon he manages to do both.