Api

From Wikanual

INTERDUBS provides an API to allow other programs interact with the system. This page is about the actual API implementation.

Contents 1 PYTHON implementation 2 Examples 3 Using the API 4 Input Parameters 4.1 idxapi_key 4.1.1 Key use quota 4.2 idxapi_function 4.2.1 create_login_wfolder 4.2.1.1 input 4.2.1.2 output 4.2.2 create_login 4.2.2.1 input 4.2.2.2 output 4.2.3 create_folder 4.2.3.1 input 4.2.3.2 output 4.2.4 create_job 4.2.4.1 input 4.2.4.2 output 4.2.5 assign_email_to_login 4.2.5.1 input 4.2.5.2 output 4.2.6 assign_look_to_login 4.2.6.1 input 4.2.6.2 output 4.2.7 assign_folder_to_login 4.2.7.1 input 4.2.7.2 output 4.2.8 assign_login_to_job 4.2.8.1 input 4.2.8.2 output 4.2.9 assign_login_to_job_id 4.2.9.1 input 4.2.9.2 output 4.2.10 list_logins 4.2.10.1 input 4.2.10.2 output 4.2.11 test_login_creds 4.2.11.1 input 4.2.11.2 output 4.2.12 get_login_info 4.2.12.1 input 4.2.12.2 output 4.2.13 login_delete_ak 4.2.13.1 input 4.2.13.2 output 4.2.14 list_folder_contents 4.2.14.1 input 4.2.14.2 output 4.2.15 list_jobs 4.2.15.1 input 4.2.15.2 output 4.2.16 list_node_ids 4.2.16.1 input 4.2.16.2 output 4.2.17 delete_node 4.2.17.1 serialized 4.2.17.2 input 4.2.17.3 output 4.2.18 delete_expired 4.2.18.1 input 4.2.18.2 output 4.2.19 delete_emptyfolders 4.2.19.1 input 4.2.19.2 output 4.2.20 get_folder_upload_handle 4.2.20.1 input 4.2.20.2 output 4.2.21 get_node_id_for_ak 4.2.21.1 input 4.2.21.2 output 4.2.22 get_node_ak_for_id 4.2.23 get_node_info 4.2.23.1 input 4.2.23.2 output 4.2.24 get_node_credit 4.2.24.1 input 4.2.24.2 output 4.2.25 add_node_credit 4.2.25.1 input 4.2.25.2 output 4.2.26 add_node_note 4.2.26.1 input 4.2.26.2 output 4.2.27 add_client_comment 4.2.27.1 input 4.2.27.2 output 4.2.28 add_client_comment2 4.2.28.1 input 4.2.28.2 output 4.2.29 get_mb_used 4.2.29.1 input 4.2.29.2 output 4.2.30 get_mb_expired 4.2.30.1 input 4.2.30.2 output 4.2.31 assign_note_to_login 4.2.31.1 input 4.2.31.2 output 4.2.31.3 Example 4.2.32 get_quota_avail 4.2.32.1 input 4.2.32.2 output 4.2.33 copy_file 4.2.33.1 input 4.2.33.2 output 4.2.34 add_email 4.2.34.1 input 4.2.34.2 output 4.2.35 send_simple_email 4.2.35.1 input 4.2.35.2 output 4.3 idxapi_par1,2 etc 4.4 idxapi_simulation 5 Return Values 5.1 Status 5.1.1 IDXAPI_ERROR: 5.1.2 IDXAPI_FAILURE: 5.1.3 IDXAPI_SIMOK: 5.1.4 IDXAPI_OK: 5.2 Data 5.2.1 Parameters in use 5.2.1.1 _AK 5.2.1.2 _BOOL 5.2.1.3 _FLOAT 5.2.1.4 _ID 5.2.1.5 _NUM 5.2.1.6 _STR 5.2.1.7 _TIME 5.2.1.8 _ULH 6 Example Code 7 Functionalities outside of the API

PYTHON implementation

In most of the cases you will probably use the python API to access functionality in a more convenient matter.

Examples

automatic upload is implemented via the API. Feel free to use it for your own needs. And please get in touch if you need any assistance in adopting implenting this.

Using the API

The INTERDUBS API is implemented via a web interface. In other words you submit information with a url (via curl,wget or python urllib for example) and will receive the return information in plain text.

For test purposes you can use the web interface directly via: this web interface

Input Parameters

idxapi_key

In order to communicate with with the API your screpts needs an api_key. You can manage you API keys in your INTERDUBS admin interface under utils. An API key gets issued against an INTERDUBS segment. It is possible to issue multiple keys for the same INTERDUBS segment.

Key use quota

Each Api key also maintains a usage counter. While it is unlikely that a user will go beserk and enter 100,000 logins, a program very easily can. That's why the API needs to limit the number of calls per day. This quota can be easily changed in the INTERDUBS admin interface. Only functions that alter contents will decrease the quota.

idxapi_function

The parameter for idxapi_function specifies what you would like the api to do for you.

A this point these are these possible functions:

create_login_wfolder

The create_login_wfolder api function will create a new login and a folder with the same name and a link between the two.

input

create_login_wfolder expects two parameters

idxapi_par1 
is the name of the login to be created. It needs to be made out of letters, numbers, - and _. 
It can be maximal 50 characters long

idxapi_par2
the password to be used. The same restrictions as for the login name do apply.

If there is a folder called /TEMPLATE/DEFAULT then it will be copied into the folder that got created for this login. See Template for details.

If the password parameter is GENERATE then the system will generate a secure random password.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: create_login_wfolder 
IDXAPI_LOGIN_ID: Num
IDXAPI_LOGIN_AK: IdxCode
IDXAPI_FOLDER_ID: Num
IDXAPI_FOLDER_AK: IdxCode

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

The function returns identification information for the login and the folder created. The _ID parameters are a number that can be used in URLs to admin interface. An example:

Assuming that your interdubs segment is called company and you received a return like

IDXAPI_LOGIN_ID: 24

then you could access the login details in the admin interface for the new login via:

http://www.interdubs.com/r/company/admin/index.php?j=logindetails&client2_id=24

This ID you also will need to use when you like to assign an email address to the login you just created.

Similarly the folder ID

IDXAPI_FOLDER_ID: 476

would relate to the folder view:

http://www.interdubs.com/r/company/admin/index.php?j=filfo_navigation&filfo_parent=476

The client interface operates not via clear number IDs but rather via 6 character codes. These will be returned via the _AK lines.

IDXAPI_LOGIN_AK: abc123

would be directly accessible via client login like:

http://www.interdubs.com/r/company/index.php?al=abc123

If you also have the folder AK

IDXAPI_FOLDER_AK: 789def

then you go directly to the folder via:

http://www.interdubs.com/r/company/index.php?al=abc123&an=789def

Please note that you don't need to specify the base folder for a login, this is the default behaviour.

The IDXAPI_FOLDER_AK value can be useful in a different context though: You can upload directly into this folder via this handle. The INTERDUBS droplet mechanism uses this key value to locate the target folder. Please see Using the droplet gateway to see how you can use this key to upload data into specific folders.

create_login

The create_login function will create a new login, but it will not have a folder assigned to it.

input

create_login expects two parameters

idxapi_par1 
is the name of the login to be created. It needs to be made out of letters, numbers, - and _. 
It can be maximal 50 characters long

idxapi_par2
the password to be used. The same restrictions as for the login name do apply.

If the password parameter is GENERATE then the system will generate a secure random password.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: create_login 
IDXAPI_LOGIN_ID: Num
IDXAPI_LOGIN_AK: IdxCode

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

The function returns identification information for the login created. See create_login_wfolder for detailed discussion of these return values

create_folder

The create_folder api function will create a new folder inside of an existing one.

input

create_folder expects two parameters

idxapi_par1 
is the name of the folder to be created. It needs to be made out of letters, numbers, - and _.  It can be maximal 50 characters long.

idxapi_par2
is the FOLDER_ID of the parent folder. This is the number in the database 
of the parent folder. The root folder has the number 1. 
You can obtain this number via the IDXAPI_FOLDER_ID return value.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: create_folder 
IDXAPI_FOLDER_ID: Num
IDXAPI_FOLDER_AK: IdxCode

The first parameter indicates success. The second one IDXAPI_FOLDER_ID the IDXAPI_FOLDER_ID of the newly created folder. And finally the six digita IdxCode that can be used during uploads.

create_job

The create_job api function will create a new job. A job can contain logins. See [jobs] for details.

input

create_job expects one parameter

idxapi_par1 
is the name of the job to be created. It needs to be made out of letters, numbers, - and _.  It can be maximal 50 characters long.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: create_folder 
IDXAPI_JOB_ID: Num

The first parameter indicates success. The second one IDXAPI_JOB_ID is a numerical identifier for the job. When you assign a login to a job you use this number. If the job already exists then the create_job function will simply give back the valid JOB_ID.

assign_email_to_login

This function will assign an email address to a login that you have already created.

input

assign_email_to_login expects two parameters

idxapi_par1 
is the ID of the login that create_login_wfolder has returned to you in the IDXAPI_LOGIN_ID: field. It should be a number.

idxapi_par2 
is the new email address that will be used as a sender email for this login.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: assign_email_to_login 

IDXAPI_OK: indicates that everything was ok. It is followed by the function name. In the case of this function there is nothing more to say for the API. It either worked, or it did not.

assign_look_to_login

This function will assign an email address to a login that you have already created.

input

assign_look_to_login expects two parameters

idxapi_par1 
is the ID of the login that create_login_wfolder has returned to you in the IDXAPI_LOGIN_ID: field. It should be a number.

idxapi_par2 
is the is id of the look to be assigned to the login. It should be a number.

The look ID can be obtained from the URL of the edit look page. It is the number following

lookcfg_id=

in the URL.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: assign_look_to_login 

IDXAPI_OK: indicates that everything was ok. It is followed by the function name. In the case of this function there is nothing more to say for the API. It either worked, or it did not.

assign_folder_to_login

This function will assign an folderto a login that you have already created.

input

assign_folder_to_login expects two parameters

idxapi_par1 
is the ID of the login that create_login_wfolder or create_login has returned to you in the IDXAPI_LOGIN_ID: field. It is a number. The admin interface also references logins with this number

idxapi_par2 
is ID of the folder that that will be assigned to the login. The folder needs to exist. This is the number that is also used in the admin interface.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: assign_folder_to_login

IDXAPI_OK: indicates that everything was ok. It is followed by the function name. In the case of this function there is nothing more to say for the API. It either worked, or it did not.

assign_login_to_job

This function will assign the login to a job by name. If the job should not exist already then it will create it.

input

assign_login_to_job expects two parameters

idxapi_par1 
is the ID of the login that create_login_wfolder has returned to you in the IDXAPI_LOGIN_ID: field. It should be a number.

idxapi_par2 
is the name of the job that the login should be assigned to. If the job does not exist already then it will be created at this point. 

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: assign_login_to_job

IDXAPI_OK: indicates that everything was ok. It is followed by the function name. In the case of this function there is nothing more to say for the API. It either worked, or it did not.

assign_login_to_job_id

This function will assign a login to a job via their IDs. Both login and job must already exist

input

assign_login_to_job_id expects two parameters

idxapi_par1 
is the ID of the login. For instance returned via create_login_wfolder. It should be a number.

idxapi_par2 
is the ID of the job that the login will be assigned to. The job already needs to exist.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: assign_login_to_job_id

IDXAPI_OK: indicates that everything was ok. It is followed by the function name. In the case of this function there is nothing more to say for the API. It either worked, or it did not.

list_logins

This function will output a complete list of all logins ordered by their creation date. Newest once come first. Since this call does not alter the database it will not deduct from your API usage quota.

input

list_logins does not use any input paramaters

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: list_logins

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_LOGINS_NUM: xxx

IDXAPI_LOGINS_NUM: returns the number of jobs that are being defined in INTERDUBS.

The following will be output for each login. It might be possible that the API will create more lines per login in the future. It is important that the receiving code looks for specific fields. Additional fields will only be added in the end. So a new login description entry will always start with IDXAPI_LOGINS_NAME_STR as the first field.

IDXAPI_LOGINS_NAME_STR: abc

IDXAPI_LOGIN_NAME_STR: each login will be output in it's own line. Each that starts with IDXAPI_LOGIN_NAME_STR:

IDXAPI_LOGINS_FOLDER_ID: num

The database ID of the folder assigned to this login.

IDXAPI_LOGINS_AK: IdxCode

The 6 digit access code for the login, used in the client interface.

test_login_creds

This function tests the credentials of one login

input

test_login_creds requires two input paramaters:

idxapi_par1
the name of the login

idxapi_par2
the password of the login

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: test_login_creds

This indicates that the API call succeeded. It does not say anything about the username/password combination. This will be indicated in the next return value. It can be either:

IDXAPI_LOGIN_STATUS: OK

or

IDXAPI_LOGIN_STATUS: UNAVAILABLE

The status "OK" is followed by the AKCODE of the login:

IDXAPI_LOGIN_AK: AKCODE

The status "UNAVAILABLE" is followed by following reason(s)

IDXAPI_NOLOGIN_NOT_FOUND

The login name / password combination does not exist

IDXAPI_NOLOGIN_NOFOLDER

The folder associated to the login does not exist

IDXAPI_NOLOGIN_EXPIRED

The login has expired

get_login_info

This function will output info about one login. Since this call does not alter the database it will not deduct from your API usage quota.

input

get_login_info requires one input paramater:

idxapi_par1
the AK of the login to output information for

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_login_info

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_LOGIN_NAME_STR: abc

IDXAPI_LOGIN_NAME_STR: The name of the login.

IDXAPI_LOGIN_PASSWORD_STR: abc

The password for the login.

IDXAPI_LOGIN_FOLDER_ID: num

The database ID of the folder assigned to this login. 0 if it is none. Can be pointing to a non existing folder.

IDXAPI_LOGIN_CREATED_TIME: utime

The time a login has been created. Expressed in a number that is the unix epoch time.

IDXAPI_LOGIN_EXPIRATION_TIME: utime

The time a login will or has been expired. Expressed in a number that is the unix epoch time. 0 if there is no expiration.

Information that is stored for a login but that is not currently available via the API includes:

page views
admin login who has created login
icon information for login
job_id that login exists in
locked flag to indicate locked state / company reel
hero_node - file to be used when only one file matters

Please get in touch if any of these values would be helpful to you. The INTERDUBS API is easily extendable.

login_delete_ak

This function deletes a login that is specified via the 6 digit IdxCode.

input

login_delete_ak expects one parameter:

idxapi_par1 
this is the 6 digit access code of the login.

output

On success and run outside of the simulation mode this function will delete the login and on success will return:

IDXAPI_OK: login_delete_ak

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

list_folder_contents

This function will output a list of files and folders inside of a folder.

input

idxapi_par1 
list_folder_contents expects the ID of the folder to list. 
The root folder has the ID 1. 

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: list_folder_contents

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_CONTENTS_NUM: xxx

IDXAPI_CONTENTS_NUM: returns the number of files / folders in the given folder

The following will be output for each file / folder. It might be possible that the API will create more lines per file / folder in the future. It is important that the receiving code looks for specific fields. Additional fields will only be added in the end. So a new login description entry will always start with IDXAPI_CONTENTS_NAME_STR as the first field.

IDXAPI_CONTENTS_NAME_STR: abc

IDXAPI_CONTENTS_NAME_STR: the name of the file /folder

IDXAPI_CONTENTS_ID: num

The database ID of the file / folder.

IDXAPI_CONTENTS_AK: IdxCode

The 6 digit access code for the file / folder.

IDXAPI_CONTENTS_ISFOLDER_BOOL: 1|0

A 1 gets returned when the listing is a folder. 0 when it is a file.

list_jobs

This function will output a complete list of all jobs ordered by the creation date. Newest once come first. Since this call does not alter the database it will not deduct from your API usage quota.

input

list_jobs does not use any input paramaters

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: list_jobs

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_JOBS_NUM: xxx

IDXAPI_JOBS_NUM: returns the number of jobs that are being defined in Interdubs. It also denotes how many lines will follow.

IDXAPI_JOB_NAME_STR: abc

IDXAPI_JOB_NAME_STR: each job be output in it's own line. Each that starts with IDXAPI_JOB_NAME_STR:

list_node_ids

This function will output of nodes in a folder that match a name

input

list_node_ids requires two input paramaters:

idxapi_par1
the name of the node to match

idxapi_par2
the folder ID to look in for the node

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: list_node_ids

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_NODE_IDS_NUM: xxx

IDXAPI_NODE_IDS_NUM: returns the number of files/ folders that match the name

IDXAPI_NODE_IDS_ID: 123

IDXAPI_NODE_IDS_ID: is the ID parameter for each file / folder that matches

further information about the node can be queried with get_node_info

delete_node

A node in INTERDUBS is either a file or folder. The delete_node deletes a file or folder.

serialized

You can only run one instance of delete_node at a time per API key. If you call this function while already a call is on the way for the same key then you will get an error message.

input

delete_node needs one parameter:

idxapi_par1
is the ID of the node to delete

output

On success and run outside of the simulation mode this function will return the following value:

IDXAPI_OK: delete_node

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

delete_expired

If you like to clean up expired files then this API will be able to do this. Depending on the amount of files it might run for a little while. You can see the space gains via the get_mb_expired API call

input

delete_expired requires one input parameter:

idxapi_par1
the number of days that files have been expired since

output

On success and run outside of the simulation mode this function will return the following value:

IDXAPI_OK: delete_expired

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

delete_emptyfolders

You can delete all empty folders with one API call. See Cleanup_empty_folders for a detailed list of rules for those deletions. The API has to set the actual age in days, while the web interface defaults to 7 days for this function.

input

delete_emptyfolders requires one input parameter:

idxapi_par1
the number of days that folders have to be created before so that they can get deleted.

output

On success and run outside of the simulation mode this function will return the following value:

IDXAPI_OK: delete_emptyfolders

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

get_folder_upload_handle

If you like to add material to INTERDUBS you need to obtain an upload handle (_UL)

input

get_folder_upload_handle requests one parameter:

idxapi_par1
is the ID of the node to get information about

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_folder_upload_handle

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_FOLDER_ULH: UploadHandle

An upload handle contains at this point two parts: The segment cname followed by the folders IdxCode. This UploadHandle allows you add material to a given folder.

get_node_id_for_ak

A node in INTERDUBS is either a file or folder. The get_node_info function outputs information about this file / folder.

input

get_node_id_for_ak requests one parameter:

idxapi_par1
is the idxCode of the note to return the id for.

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_node_id_for_ak

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

After this the function returns the node_id for the node in question:

IDXAPI_NODE_ID: Num 

get_node_ak_for_id

This is identical to get_node_info and exists only for clarity. It is the preferred way to access this.

get_node_info

The name of this function will be deprectated. Please use get_node_ak_for_id instead.

A node in INTERDUBS is either a file or folder. The get_node_info function outputs information about this file / folder.

input

get_node_info requests one parameter:

idxapi_par1
is the ID of the node to get information about

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_node_info

IDXAPI_OK: indicates that everything was ok. It is followed by the function name. After this the function returns details about the file. Future versions might return more information. Updates will always append information in the end of the file.

IDXAPI_NODE_AK: IdxCode

get_node_credit

A node in INTERDUBS is either a file or folder. The get_node_credit function outputs the credit information associated with a note

input

get_node_credit requests one parameter:

idxapi_par1
is the ID of the node to get the credits for

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_node_credit

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_CREDITS_NUM: xxx

xxx stands for the number of defined credits. For each credit there are 3 output lines:

IDX_CREDIT_SCORE_FLOAT: xxx
IDX_CREDIT_ROLE: abc
IDX_CREDIT_PERSON: def

where xxx is the credit score (a rank for the role during display), abc the role of the credit (the type) and def the person (or value)

add_node_credit

The add_node_credit function adds one credit to a file or folder

input

add_node_credit requests three parameters:

idxapi_par1
is the ID of the node to add the credits for

idxapi_par2
the name of the role of the credit. credit_roles that don't exist will be added. 
They need to get a score added to.

idxapi_par3
the credit value (the person) 

output

On success and run outside of the simulation mode this function will return:

IDXAPI_OK: add_node_credit

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

add_node_note

The add_node_note function adds a note to a file or folder

input

add_node_note requests two parameters:

idxapi_par1
is the ID of the node to add the note to

idxapi_par2
the note to be added to the node

output

On success and run outside of the simulation mode this function will return:

IDXAPI_OK: add_node_note

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

add_client_comment

The add_client_comment function adds a client comment to a file. We recommend using add_client_comment2 since it offers more functionality

input

add_client_comment requests two parameters:

idxapi_par1
is the ID of the node to add the comment to

idxapi_par2
the comment to be added to the node

output

On success and run outside of the simulation mode this function will return:

IDXAPI_OK: add_client_comment

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

add_client_comment2

The add_client_comment2 function adds a client comment to a file.

input

add_client_comment2 requests three parameters:

idxapi_par1
is the AK code of the node to add the comment to

idxapi_par2
the comment to be added to the node

idxapi_par3
the name of the author of the comment

output

On success and run outside of the simulation mode this function will return:

IDXAPI_OK: add_client_comment2

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

get_mb_used

This function will output the amount of storage used by your INTERDUBS segment in Megabytes.

input

get_mb_used does not use any input paramaters

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_mb_used

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_MB_USED_FLOAT: xxx.yyy

IDXAPI_MB_USED_FLOAT: returns the amount of storage being occupied by your INTERDUBS segment in Megabytes.

get_mb_expired

This function will output the amount of storage that is occupied by by expired files in Megabytes.

input

get_mb_expired requires one input parameter:

idxapi_par1
the number of days that files have been expired since

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_mb_expired

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_MB_EXPIRED_FLOAT: xxx.yyy

IDXAPI_MB_EXPIRED_FLOAT: returns the amount of storage being occupied by expired files in your INTERDUBS segment in Megabytes.

assign_note_to_login

This function will assign an internal login note to a login.

input

assign_note_to_login requests two parameters:

idxapi_par1
is the ID of the login to add the internal note to

idxapi_par2
the note to be added to the login

The note can have a maximum length of 200 characters.

output

On success and run outside of the simulation mode this function will return:

IDXAPI_OK: assign_note_to_login

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

Example

This function comes in handle when you like to assign email addresses to logins via the internal note, so that you can use Email_distribution lists.

get_quota_avail

This function will output the quota that is left for a given API key. It also is a convenient way to check if the API key is valid etc.

input

get_quota_avail does not use any input parameters

output

On success and run outside of the simulation mode this function will return the following values:

IDXAPI_OK: get_quota_avail

IDXAPI_OK: indicates that everything was ok. It is followed by the function name.

IDXAPI_QUOTA_AVAIL_NUM: 123

IDXAPI_QUOTA_AVAIL_INT: returns the number of API uses that are left for this day. You can raise the quota easily in the INTERDUBS admin interface. If the key should be invalid then this call returns a negative number.

IDXAPI_SEGMENT_NAME: acme

IDXAPI_SEGMENT_NAME is followed by the name of the INTERDUBS segment.

copy_file

This function will copy a file into a folder.

input

copy_file requires two parameters:

idxapi_par1
is the ID of the file to be copied

idxapi_par2
is the ID of the folder that the the file will be copied into

output

On success this function will return:

IDXAPI_OK:  copy_file

After this the function returns the node_id of the newly created file:

 IDXAPI_NODE_ID: Num

add_email

This function will add an email address to the address book of the segment.

input

add_email requires one parameter:

idxapi_par1

the email address to be added

output

On success this function will return:

IDXAPI_OK:  add_email

After this the function returns the email_id of the email address.

 IDXAPI_EMAIL_ID: Num

This function can also be used to obtain the email_id of a given email address.

send_simple_email

This function will send an email from the system with info for a login

input

send_simple_email requires two parameters:

idxapi_par1

The ID of the login.

idxapi_par2

The email address that should receive the email.

output

On success this function will return:

IDXAPI_OK: send_simple_email

idxapi_par1,2 etc

API functions can have one or more input parameters. The meaning of the parameters depends on the function itself. Please refer to the documentation of the actual function.

idxapi_simulation

When you just like to test your code without altering the actual interdubs segment the simply add this parameter with a value of 1. The API will behave exactly like it would in a real situation, just that the data of the interdubs segment will not be altered.

The Interdubs API in simulation mode will get expose all possible FAILURE conditions. Once your call passes the simulation mode it will also exexcute for real, unless there is an ERROR. See below for the difference of FAILURE and ERROR.

A two second delay in simulation mode guards against accidental over use of the API. Calls with the simulation flag on will return IDXAPI_SIMOK and no additional data.

Return Values

Status

A call to the API results at least in a status message. This is always exclusively one of the following four:

IDXAPI_ERROR:

IDXAPI_ERROR indicates that an error occured during the process of your request. These should never happen. They indicate that something does not work as intented. Very likely it is not cause by something that the API caller did do. Please notify Interdubs of such errors and what led to them.

IDXAPI_FAILURE:

IDXAPI_FAILURE: A failure indicates that what you intended to do could not be executed. The reasons for this are very likely to be caused by the calling data. Not having a valid api key, trying to create a login/password that already exists: These conditions will result in a failure.

IDXAPI_SIMOK:

A call with the simulation flag on was processed successfully. No data has been altered and nothing else will be returned.

IDXAPI_OK:

The process was sucessfully proccessed. Depending on the request more data might follow.

Data

The Interdubs API returns data in a similar to the status message. Lines of text starting with IDXAPI_ . Please refer to the function explaination for details. In general the type of returned value is the last part of the return value name.

Parameters in use

_AK

A return name ending with _AK identifies an Access Key for an element in the database as a six digit case sensitve string. These values are mostly used in the client interface and other public accessible parts of the system. Sometimes the Access Key AK is also referred to as an IdxCode.

_BOOL

_BOOL is a boolean value that can be either 1 or 0.

_FLOAT

_FLOAT is a number with a fractional part.

_ID

A return name ending with _ID identifies an ID of an element in the database as a number. These values are mostly used in the admin interface

_NUM

_NUM is used when the following value is a number without any fractions. Like the number of jobs.

_STR

_STR is used then the rest of the line is a text string.

_TIME

A unix time stamp. Counting seconds since January 1st 1970. Looks just like a big number, since it is one.

_ULH

A return name ending with _ULH specifies an Upload Load Handle. An upload handle can be used to add files to the system. It contains two parts: the segments cname and the Access key of the target folder.

Example Code

A very simple example in perl that you can download and run, once you have generated your API key. This code shows you how to use the create_login_wfolder function. It also illustrates how to obtain returned values.

An even simpler example in python. This will get a list of all logins and return their names, folder IDs and IdxCode access keys. please Look for more complete and easy to use examples in the python API section of the documentation.

Functionalities outside of the API

Many things in relationship to creating data inside of INTERDUBS can be accomplished outside of this API. Ftp#meta_data for instance allows the population of data via simple and robust means.