This is the first in our series on Web Services integration with FileMaker that I mentioned last week.
DropBox
The API we are going to look at today is DropBox. With this API a FileMaker solution can manage and share files, folders and Dropbox Paper documents.
As an example, when someone signs up to sponsor the BaseElements plugin, we share with a them a DropBox folder with every historical version of the plugin, as well as private beta versions with new functionality.
We do that with a FileMaker script that uses the BaseElements plugin to do HTTP calls to the Dropbox API. If you missed the first article of the series, it is an introduction to the world of web services and FileMaker.
Each interaction with the web service starts with a request from FileMaker sent to a specific url (or endpoint) along with the request parameters.
A request URL will look something like this:
https://api.dropboxapi.com/2/files/list_folder
This endpoint returns the contents of a folder.
The URL breaks down (reading backward) to: i want to use the list_folder function from the files category of the version 2 of the dropbox api. Makes sense? The first part will be the same in all our requests, the only parts that will change will be the function and the category.
Of course we also need to tell the Dropbox API what folder we are talking about and that is done through the parameters (or body) of the request, using JSON:
{
"path": "/Goya/Secret_Projects"
}One detail to remember about the Dropbox API is that it uses POST requests even for endpoints where we get data.
So the previous example called from FileMaker with the BaseElements plugin will be
BE_HTTP_POST ( "https://api.dropboxapi.com/2/files/list_folder" ; "{ "path": "/Goya/Secret_Projects"}" ; "" ; "")
If you go ahead and try that the API will send back an error (at least we know they answer!).
The request can’t be processed because we haven’t yet told the API what dropbox account we want to use.
So let’s go back to our workflow for the Goya sponsors: we have an email address (we receive it from another API) and we want to share our folder with them.
Based on what we said, to successfully process the request Dropbox needs to know:
- that we are authorized to interact with that Dropbox account
- what folder do we want to share
- who are we sharing the folder with and what privileges will they have on the folder and files
Authorization
To identify what Dropbox account we want to work on we need to tell the API that we are authorised to work on it. You do that by getting a token.
The token can be obtained going to this address https://www.dropbox.com/developers/apps and following the steps to register an app and create a token for that app.
Once we have a token, we can add an Authorization HTTP header to the request, and again we can do this with the BaseElements plugin :
BE_HTTP_Set_Custom_Header ( "Authorization" ; "Bearer " & Table::API Token )
Another header we want to add is the language we are using to send the body of our request. In our case it is JSON :
BE_HTTP_Set_Custom_Header ( "Content-Type" ; "application/json" )
Get the Folder list
We need to know the ID of the shared folder so that we can add our new sponsor to it.
The endpoint https://api.dropboxapi.com/2/sharing/list_folders returns a list of all the shared folders from the Dropbox account.
In the body we can specify a limit for the number of items returned.
The following call will return up to 1000 shared folders
BE_HTTP_POST ( "https://api.dropboxapi.com/2/sharing/list_folders" ; "{ "limit": 1000 }" )
The API will have one “entry” node for each shared folder
{
"entries": [
{
"access_type": {
".tag": "editor"
},
"path_lower": "/secret projects",
"name": "Secret Projects",
"permissions": [
],
"policy": {
"member_policy": {
".tag": "anyone"
},
"resolved_member_policy": {
".tag": "anyone"
},
"acl_update_policy": {
".tag": "editors"
},
"shared_link_policy": {
".tag": "anyone"
},
"viewer_info_policy": {
".tag": "enabled"
}
},
"preview_url": "https://www.dropbox.com/somelink",
"shared_folder_id": "123456789"
},
...
]
}We can parse the JSON using the function BE_JSONPath. So to grab the ID of the first shared folder we’ll write
BE_JSONPath ( $json ; "$.entries[0].shared_folder_id" )
Share the folder
Now that we know the token, the shared folder id and the email we want to share with, we are ready for the last call to the API.
The endpoint to add a new member to a folder is, surprisingly, https://api.dropboxapi.com/2/sharing/add_folder_member.
The body of the request will look like this
{
"shared_folder_id": "123456789",
"members": [
{
"member": {
".tag": "email",
"email": "salvatore@goya.com.au"
},
"access_level": {
".tag": "viewer"
}
}
],
"quiet": false
}where we specify the folder id, the email of the new member and what access privileges they will have.
Calling our BE_HTTP_POST with this url and body will add the member to the folder.
Success! This call doesn’t return anything if successful, so we’ll have to check the HTTP response header to know if everything went well.
If BE_HTTP_Response_Code returns 200, we know the email was added.
These are only two of the actions available through the Dropbox API and they were all we needed for this workflow.
A complete example file is available to sponsors of the BaseElements plugin, and is sitting in their DropBox share folder already.
Up next in the series, integrating FileMaker and Zendesk.
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.