Python API

From Wikanual

Jump to: navigation, search

Contents

INTERDUBS Python API

While the Api documentation outlines the inner workings of the INTERDUBS API mechanism most uses will be probably covered via the python API that is described here. The python api is implemented via this python module.

It contains two sets of functions. High level user functions that get things done for you. And low level function that wrap API functionalities into python functions.


Example

The Python API example will show you step by step how you can interact with the INTERDUBS Python API interface.

High level function

check_api()

This function will test if you have a proper API key and if you have uses left on your API quota. It is worth calling before you do actual work with the API.

chkmkpath(path)

This function will see if the path that it is parameter does exist already in INTERDUBS, and if it does not, then it will create it for you. It is worth calling before you start an upload.

node_delete_path(path)

This function will remove the file or folder described by its path. In the case of a folder all contents within the deleted folder will also be removed. Needless to say that you should use this function with caution.


uploadfile_into_ak (source-file-path, idxCode [[[[replace="1"] title ] note ] tags ] credits] )

This function uploads the file described in source-file-path into the folder specified by the AK six digit idxCode .


uploadfile_into_path (source-file-path, interdubs-path [[[[replace="1"] title ] note ] tags ] credits] )

This function uploads the file described in source-file-path into the folder specified by the path.

The interdubs-path must exist when you do so, so it is recommended to call chkmkpath(interdubs-path) before you call this function.


uploadfile_into_node (source-file-path, node [[[[replace="1"] title ] note ] tags ] credits] )

This function uploads the file described in source-file-path into the folder specified by the node id.

All other parameters are optional. The first one is replace and its default is 'on'. Which means that a file by the same name will be replaced by the file that gets uploaded.

The deletion takes place instantly, while the upload / ingest is asynchronous.

You can populate meta data for the uploaded file via the optional parameters. See Ftp#meta_data for details about those fields.

dictionary_to_credits(dictionary)

This function will convert a python dictionary into the format that the INTERDUBS credit format expects. The credits format can be used for a wide variety of data that can be expressed as a python dictionary.

An example use could look like:

idx = Interdubs(IDX_PATH, IDX_KEY)

idxpath =  "/uploadtest/"
idx.chkmkpath (idxpath)

dict = { 'credit1': 'credone', 'credit2': 'credtwo' }
idx.uploadfile_into_path ( "localpath", idxpath , "0" , "", "" , "" , dict)

Low level function

Low level functions in general map the actual API calls one to one.


get_quota_avail()

Checks if your Key is valid and and how many uses are left are your in quota.

Returns a number, negative if there is a problem.

get_segment_name()

Returns the name of the INTERDUBS segment that is associated with the API key.

node_delete_id(node_id)

Deletes the folder or node identified by a numeric Node_Id.

Returns nothing.

node_exists( filename , folderid)

Checks if the filename defined as a string exists in the folder with folderid. Returns the node_id of the file / folder or 0 if it does not.

get_folder_upload_handle( node_id)

Returns the upload handle for a given folder ID identified by a number. An upload handle can be used via ftp uploads.

get_ak_for_node(node_id) DEPRECATED

This function is no longer available.

Use the more consistently named version

get_node_ak_for_id

instead. It will also return the AK (Access Code) for a given file or folder identified by a folder ID.

get_node_ak_for_id(node_id)

return the AK (Access Code) for a given file or folder identified by a folder ID.

get_login_info(ak)

This function accepts the ak id of a login and returns the following variables:

client2_name, password, folder_id, created, expiration = idx.get_login_info('YOURAK');

Replace YOURAK with the ak-id of the login that you like to obtain the info for.

create_dir (name , folderid)

Create a new folder with the name inside of the folder identified by a folder ID.

list_logins()

list all logins. It returns a list of dictionaries. Each login is one dictionary. This would list its contents:

loginlist = idx.list_logins()

for l in loginlist:
        print "login name:" + l['name']
        print "folder node id: " +  l['folder']
        print "ak key: " + l['ak']
        print ""

create_login (name, password )

Creates a new login with the name and password it got as parameters

login_delete_ak (ak)

deletes the login associated with the ak handle

get_nodeid_forpath (path )

Returns the folder ID for a file or folder identified by a path.

add_node_note (node_id, "note content")

Adds a note to the node identified by the node_id. The existing note will be overwritten.


delete_expired ( days )

This call will delete all files that expired longer than the number of days in the calling parameter. This is much like clicking on the corresponding function in manage expired files ... in the admin interface.

get_mb_expired ( days )

Will return the size of all files expired longer than the days parameter.


get_mb_used ()

Will return the total size used by the entire segment.

assign_note_to_login(node_id, "note content")

Adds an internal note to the login identified by the login_id. Any existing note would be overwritten. This function is handy for instance if you like to populate email addresses for Email distribution list situations. The following script would read a csv file with name, password and email: and create logins pointing to the folder 1234:

#!/usr/bin/env python 
import sys
from interdubs_api import Interdubs
IDX_PATH            = 'http://www.interdubs.com/api/'
IDX_KEY             = 'your API key goes here'

idx = Interdubs(IDX_PATH, IDX_KEY)

fd = open (sys.argv[1], "rt")
try: 
	for line in fd:
		line = line.rstrip()
		elem = line.split (',')
		print "about to create login_name: [%s] password: [%s] email: [%s]" % (elem[0] ,elem[1], elem[2])
		id = idx.create_login(elem[0] , elem[1] )
		idx.assign_folder_to_login(id, 1234)
		idx.assign_note_to_login(id, elem[2])
		
finally:
	fd.close



Concepts

API Key

Before you can work with the API you need to create an API key. You can do to so in your INTERDUBS admin interface under utilities -> API. It is common to create a key for each of you scripts. In order to see if your valid is active you can call check_api()

Quotas

Keys have quotas. These quoatas are a simple precautionary measure against accidental DoS events issued by a script that runs haywire. After the quota of a script has been exhausted it will have no effect until its number gets reset. Either automatically at mid night, or manually in the Admin interface. Only functions that change data in INTERDUBS will decrease your quota. Look ups will not decrease them.

Keys are bound to a segment

While all INTERDUBS clients use the same API, the Key is actually bound to a specific INTERDUBS segment. With a Key you get access to the INTERDUBS API and the segment that you have created it in.



describing parts of INTERDUBS

IDs

INTERDUBS stores items in a database that can be accessed via a simple numeric ID. Once you authenticated your access with the system you can operate on these IDs. Each segment (INTERDUBS client) as its own name space for these numberic IDs. Since you access content via the API key that is bound to a given segment it is not possible to gain access to data in other segments. Be it accidental or maliciously.

The folder ID 1 for instance in the root folder for your segment.

Access Keys

When you access the system in a non authenticated way then you do so via access keys. Each node has a unique Access Keys. The Api has functions to operate on these access keys. But in the python implementation you never need to worry about this level of access.


Paths

It is common to describe a storage location by a path. In a path folder names are seperated via / characters. The INTERDUBS API does not support paths, but the python module described here does translate paths to the required INTERDUBS IDs and Keys as needed. This translation works as long

the same file / folder-name is not being used in a folder repeatedly. INTERDUBS will  
use the first match it finds
the / character is not used in a name. 

Both things are possible since INTERDUBS stores data in a database, and therefor does not inherit limitations of file-system name spaces

Personal tools