DropBox API v2 library.

dropboxapi.lua

-- DropBox API v2 Library

require("utils") -- https://gist.github.com/HoraceBury/9321964
local iolib = require("iolib") -- https://gist.github.com/HoraceBury/d8d2fa3382f82a7c7faa
iolib.isdebug = false

local lib = {}

local function printer(str)
	iolib.isdebug = lib.IsDebug
	
	if (lib.IsDebug) then
		print(str)
	end
end

local function dumper(tbl)
	iolib.isdebug = lib.IsDebug
	
	if (lib.IsDebug) then
		dump(tbl)
	end
end

local function makeCallback( callback, event )
	if (callback) then
		callback( event )
	end
end

--[[
	General DropBox HTTP API documentation can be found here:
		https://www.dropbox.com/developers/documentation/http/documentation
	
	DropBox access via this library is for app access only. It is not designed to allow users to authenticate.
	It allows your app to access a special folder in your DropBox account created specifically for your app,
	within your regular folders, located at:

		\DropBox\Apps\<your app name>
	
	This means that while you can browse and edit the files in the app's folders, the app cannot access
	files outside of its own space.
]]--

--[[
	The DropBox curl commands have been included in this library to explain how the calls work,
	but are not required knowledge.
]]--

--[[
	The bearer token is an app specific token generated on the app page. To get the bearer token,
	login to your DropBox account and go to:
		https://www.dropbox.com/developers/apps
	Create an app and on it's page, which will be something like:
		https://www.dropbox.com/developers/apps/info/a1bcd23456efghi
	under "Generated access token" click the "Generate" button to get a bearer token, something like:
		Ai3JQHK2F60ABCDEFGDUUfdDrEo8boDXB321At3K6iHRjRYGXKQBTYUIOPQ-1234
	Copy that token into the 'BearerToken' string below.
]]--
lib.BearerToken = nil

--[[
	Set to true to see debug output, otherwise set to false.
	Setting to true will cause the iolib library to also output debug data.
]]--
lib.IsDebug = false

--[[
	All function parameters will appear in this order:
	
	filename: absolute filename of the local file
	base: directory constant, see: https://docs.coronalabs.com/api/type/Constant.html#directory-constants
	path: the folder path on the dropbox server. "" is the root folder. Any other folder path must start with "/"
	recursive: true to include all sub-folders, false to include only the named folder
	callback: function called when the operation is complete, accepts network.request event object
]]--

function lib.upload(filename, base, path, callback)
	printer("dropboxapi.upload()")
	
	local function networkListener( event )
		dumper(event)
		makeCallback( callback, event )
	end
 
	local headers = {}
  
	headers["Authorization"] = "Bearer "..lib.BearerToken
	headers["Content-Type"] = "application/octet-stream"
	
	local Dropbox_API_Arg = [[{
		"path": "]]..path..[[",
		"mode": "overwrite",
		"autorename": true,
		"mute": false,
		"strict_conflict": false
	}]]
	
	local params = {}
	params.headers = headers
	params.body = {
		filename = filename,
		baseDirectory = base
	}
	
	network.request( "https://content.dropboxapi.com/2/files/upload?arg="..string.urlencode(Dropbox_API_Arg), "POST", networkListener, params )
end
--lib.upload("readme.txt", system.ResourceDirectory, "/user/readme.txt")

--[[
curl -X POST https://content.dropboxapi.com/2/files/upload \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Dropbox-API-Arg: {\"path\": \"/user/readme.txt\",\"mode\": \"add\",\"autorename\": true,\"mute\": false,\"strict_conflict\": false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @readme.txt
]]--

function lib.delete(path, callback)
	printer("dropboxapi.delete()")
	
	local function networkListener( event )
		dumper(event)
		makeCallback( callback, event )
	end
 
	local headers = {}
  
	headers["Authorization"] = "Bearer "..lib.BearerToken
	headers["Content-Type"] = "application/json"

	local body = [[{
		"path": "]]..path..[["
	}]]
	
	local params = {}
	params.headers = headers
	params.body = body

	network.request( "https://api.dropboxapi.com/2/files/delete_v2", "POST", networkListener, params )
end
--lib.delete("/user28")

--[[
curl -X POST https://api.dropboxapi.com/2/files/delete_v2 \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/user\"}"
]]--

function lib.create_folder_v2(path, callback)
	printer("dropboxapi.create_folder_v2()")
	
	local function networkListener( event )
		dumper(event)
		makeCallback( callback, event )
	end
 
	local headers = {}
  
	headers["Authorization"] = "Bearer "..lib.BearerToken
	headers["Content-Type"] = "application/json"
	
	local body = [[{
		"path": "]]..path..[[",
		"autorename": true
	}]]
 
	local params = {}
	params.headers = headers
	params.body = body

	network.request( "https://api.dropboxapi.com/2/files/create_folder_v2", "POST", networkListener, params )
end
--lib.create_folder_v2("/user28")

--[[
curl -X POST https://api.dropboxapi.com/2/files/create_folder_v2 \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/user28\",\"autorename\": true}"
]]--

function lib.list_folder(path, recursive, callback)
	printer("dropboxapi.list_folder()")
	
	local function networkListener( event )
		dumper(event)
		makeCallback( callback, event )
	end
 
	local headers = {}
  
	headers["Authorization"] = "Bearer "..lib.BearerToken
	headers["Content-Type"] = "application/json"

	local body = [[{
		"path": "]]..path..[[",
		"recursive": ]]..tostring(recursive)..[[,
		"include_media_info": false,
		"include_deleted": false,
		"include_has_explicit_shared_members": false,
		"include_mounted_folders": false
	}]]
 
	local params = {}
	params.headers = headers
	params.body = body

	network.request( "https://api.dropboxapi.com/2/files/list_folder", "POST", networkListener, params )
end
--lib.list_folder("", true)

--[[
curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"\",\"recursive\": true,\"include_media_info\": false,\"include_deleted\": false,\"include_has_explicit_shared_members\": false,\"include_mounted_folders\": true}"
]]--

function lib.download(filename, base, path, callback)
	printer("dropboxapi.download()")
	
	local function networkListener( event )
		dumper(event)
		iolib.write( filename, base, event.response )
		makeCallback( callback, event )
	end
 
	local headers = {}
  
	headers["Authorization"] = "Bearer "..lib.BearerToken
	
	local params = {}
	params.headers = headers
	
	local Dropbox_API_Arg = [[{
		"path": "]]..file..[["
	}]]
	
	network.request( "https://content.dropboxapi.com/2/files/download?arg="..string.urlencode(Dropbox_API_Arg), "POST", networkListener, params )
end
--lib.download("readme.txt", system.DocumentsDirectory, "/user/readme.txt")

--[[
curl -X POST https://content.dropboxapi.com/2/files/download \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Dropbox-API-Arg: {\"path\": \"/user/readme.txt\"}"
]]--

function lib.download_zip(filename, base, path, callback)
	printer("dropboxapi.download_zip()")
	
	local function networkListener( event )
		dumper(event)
		iolib.write( filename, base, event.response )
		makeCallback( callback, event )
	end
 
	local headers = {}
  
	headers["Authorization"] = "Bearer "..lib.BearerToken
	
	local params = {}
	params.headers = headers
	
	local Dropbox_API_Arg = [[{
		"path": "]]..path..[["
	}]]
	
	network.request( "https://content.dropboxapi.com/2/files/download_zip?arg="..string.urlencode(Dropbox_API_Arg), "POST", networkListener, params )
end
--lib.download_zip( "user.zip", system.DocumentsDirectory, "/user" )

--[[
curl -X POST https://content.dropboxapi.com/2/files/download_zip \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Dropbox-API-Arg: {\"path\": \"/user\"}"
]]--

function lib.get_metadata(path, callback)
	printer("dropboxapi.get_metadata()")
	
	local function networkListener( event )
		dumper(event)
		makeCallback( callback, event )
	end
 
	local headers = {}
  
	headers["Authorization"] = "Bearer "..lib.BearerToken
	headers["Content-Type"] = "application/json"
	
	local body = [[{
		"path": "]]..path..[[",
		"include_media_info": false,
		"include_deleted": false,
		"include_has_explicit_shared_members": false
	}]]
	
	local params = {}
	params.headers = headers
	params.body = body
	
	network.request( "https://api.dropboxapi.com/2/files/get_metadata", "POST", networkListener, params )
end
--lib.get_metadata( "/user" )

--[[
curl -X POST https://api.dropboxapi.com/2/files/get_metadata \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/user\",\"include_media_info\": false,\"include_deleted\": false,\"include_has_explicit_shared_members\": false}"
]]--

return lib

main.lua

-- DropBox API v2 Demo

display.setStatusBar( display.HiddenStatusBar )
display.setDefault( "background", .9 )

local json = require("json")

local dropboxapi = require("dropboxapi")
dropboxapi.IsDebug = true
dropboxapi.BearerToken = -- see dropboxapi.lua documentation comments for the acquiring the BearerToken from DropBox

--[[
	To use this example main.lua, place a file called 'readme.txt' in the same folder.
	
	The curl statements are kept simply to explain the mechanisms in a common language.
]]--

--dropboxapi.upload("readme.txt", system.ResourceDirectory, "/user/readme.txt")

--[[
curl -X POST https://content.dropboxapi.com/2/files/upload \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Dropbox-API-Arg: {\"path\": \"/user/readme.txt\",\"mode\": \"add\",\"autorename\": true,\"mute\": false,\"strict_conflict\": false}" \
    --header "Content-Type: application/octet-stream" \
    --data-binary @readme.txt
]]--

--dropboxapi.delete("/user28")

--[[
curl -X POST https://api.dropboxapi.com/2/files/delete_v2 \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/user\"}"
]]--

--dropboxapi.create_folder_v2("/user28")

--[[
curl -X POST https://api.dropboxapi.com/2/files/create_folder_v2 \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/user28\",\"autorename\": true}"
]]--

--dropboxapi.list_folder("", true, function(event)
--	print( json.prettify( event.response ) )
--end )

--[[
curl -X POST https://api.dropboxapi.com/2/files/list_folder \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"\",\"recursive\": true,\"include_media_info\": false,\"include_deleted\": false,\"include_has_explicit_shared_members\": false,\"include_mounted_folders\": true}"
]]--

--dropboxapi.download("readme.txt", system.DocumentsDirectory, "/user/readme.txt")

--[[
curl -X POST https://content.dropboxapi.com/2/files/download \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Dropbox-API-Arg: {\"path\": \"/user/readme.txt\"}"
]]--

--dropboxapi.download_zip( "user.zip", system.DocumentsDirectory, "/user" )

--[[
curl -X POST https://content.dropboxapi.com/2/files/download_zip \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Dropbox-API-Arg: {\"path\": \"/user\"}"
]]--

--dropboxapi.get_metadata( "/user" )

--[[
curl -X POST https://api.dropboxapi.com/2/files/get_metadata \
    --header "Authorization: Bearer <bearer token from https://www.dropbox.com/developers/apps -> App -> Generate access token>" \
    --header "Content-Type: application/json" \
    --data "{\"path\": \"/user\",\"include_media_info\": false,\"include_deleted\": false,\"include_has_explicit_shared_members\": false}"
]]--

z.ReadMe.md

DropBox API v2 Library

Required dependencies

`https://gist.github.com/HoraceBury/9321964`
`https://gist.github.com/HoraceBury/d8d2fa3382f82a7c7faa`

DropBox API Docs

General DropBox HTTP API documentation can be found here:

`https://www.dropbox.com/developers/documentation/http/documentation`

Aim

DropBox access via this library is for app access only. It is not designed to allow users to authenticate.

It allows your app to access a special folder in your DropBox account created specifically for your app, within your regular folders, located at:

`\DropBox\Apps\<your app name>`

This means that while you can browse and edit the files in the app's folders, the app cannot access files outside of its own space.

Why curl?

The DropBox curl commands have been included in this library to explain how the calls work, but are not required knowledge.

Bearer Token

The bearer token is an app specific token generated on the app page. To get the bearer token, login to your DropBox account and go to:

`https://www.dropbox.com/developers/apps`

Create an app and on it's page, which will be something like:

`https://www.dropbox.com/developers/apps/info/a1bcd23456efghi`

...under Generated access token click the Generate button to get a bearer token, something like:

`Ai3JQHK2F60ABCDEFGDUUfdDrEo8boDXB321At3K6iHRjRYGXKQBTYUIOPQ-1234`

Copy that token into the dropboxapi.BearerToken variable.

Debug Output

Set dropboxapi.IsDebug to true to see debug output, otherwise set to false. Setting to true will cause the iolib library to also output debug data. Default is false.

Library Function Parameters

All function parameters will appear in this order:

• filename: absolute filename of the local file
• base: directory constant, see: https://docs.coronalabs.com/api/type/Constant.html#directory-constants
• path: the folder path on the dropbox server. "" is the root folder. Any other folder path must start with "/"
• recursive: true to include all sub-folders, false to include only the named folder
• callback: function called when the operation is complete, accepts network.request event object