February 22, 2012, Wednesday, 52

API Interfacing

From Mobitouch cube

Jump to: navigation, search

Contents

Overview

APIs provide management of nodes, campaigns and files through command line.

APIs integrates easily to mobitouch system, by using the same approach as the web based CMS.

WARNING: API interfacing is allowed only for companies using whitelabel option.


In order to use any of the API functions, the user must be logged in, to ensure access to the system is granted only to allowed users.

Log in to the system with APIs must be performed at each call.

APIs use a stateless communication protocol, which won't keep the identity of any logged user.

User's actual identity will be checked at each call.


All the following examples are done with CURL (http://curl.haxx.se/) following its standard syntax.


There are three main sections for API use.

Node

management of nodes for current user.

  • Can obtain list of currently activated nodes for own company.
  • Can obtain configuration parameters for a single node.
  • Can set configuration parameters for a single node.

File

management of files on the system for current user.

  • Can upload a new file to the system.
  • Can obtain the list of files currently uploaded on the system.
  • Can delete a file from the system, if the file is not currently in use.

Campaign

management of campaigns for current user.

  • Can obtain a list of currently defined campaigns for own company.
  • Can create a new campaign, with at least one schedule, and one content with simple policy.
  • Can modify campaign basic details for a single campaign.
  • Can get currently defined schedules for a single campaign.
  • Can set new schedules for a single campaign.
  • Can obtain a list of currently defined contents for a single campaign.
  • Can set new contents, only "simple" policy, for a single campaign.
  • Can get a list of nodes currently associated to a single campaign.
  • Can set a list of nodes to deploy a single campaign.


Message codes

Every call to API methods will return an XML fomatted text, containing a status, a return code and, in case, the actual XML containg required information, if no errors are reported.
In case of errors, the system returns also a message, briefly explaining the reason of the error.


The status will have only two values, 0 that means failure, and 1 that means success.
For example, the following configuration means successful call. 

...
<status>1</status>
...


The return code can be one in the following list.


  • 100: Call successful, everything was ok.

   The resulting XML is also returned to the user.


  • 200: Authentication is failed, username or password are wrong.

   This error code is also returned when the authenticating user does not belong to a Waymedia whitelabel company, even if credential are correct.

  • 201: The authenticated user is not allowed to requested resource (nodes, campaigns, files...).

   The user is granted access only to he resources belonging to his own company.

  • 202: The requested action is not allowed.

   Not all actions can be performed, in order to preserve system integrity.


  • 300: Expected parameters are wrong.

   The system is expecting parameters different from those submitted by the user.

  • 301: The file to submit is missing.

   A file is expected by the API call, for example in case of upload, but the actual file is missing or not correctly submitted.

  • 302: Submitted file is too big.

   The maximum file size for a single file upload is set to 10485760 bytes, 10 MB.


  • 400: An internal error has occurred.
  • 401: Requested resource (nodes, campaigns, files...) is not present in the system.


Authentication of the user

To authenticate a user through API, the system is expecting a XML file containing user's information. The file MUST HAVE the following structure: 

<login>
    <username>YourUsername</username>
    <password>YourPassword</password>
</login>

The file must be submitted to the system url in the following way. 

	
	curl -F "login=@loginFile.xml" "cms.mobitouchcube.com/api/rest/myAction?method=myMethod"

The login file must be passed to the url with the "login" key. Thus, option ' -F "login=@..." ' is compulsory.

If the authentication fails, further operations are aborted and an error code is returned.


Node management

(api/rest/node)

Get the list of your nodes

A list of nodes currently activated on user's compan y can be obtained in the following way: 

 	curl -F "login=@loginFile.xml" "cms.mobitouchcube.com/api/rest/node?method=getNodes"

For each node there will be some basic information.


Get configuration parameters for a node

Configuration parameters for a single node can be get in the following way: 

	curl -F "login=@loginFile.xml" "cms.mobitouchcube.com/api/rest/node?method=getNodeParameters&node_id=XX"

where in "node_id=XX" XX is the node_id of desired node, that can be obtained by previous method "getNodes".


Set configuration parameters for a node

Configuration parameters for a single node can be set in the following way: 

	
	curl -F "login=@loginFile.xml" -F "config=@nodeParameters.xml" "cms.mobitouchcube.com/api/rest/node?method=setNodeParameters&node_id=XX"

In "node_id=XX" XX is the node_id of the node to modify.

New configuration for a node can be obtained uploading a XML file containing all nodes parameters.

The configuration file must be passed to the url with the "config" key. Thus, option ' -F "config=@..." ' is compulsory, the file nodeParameters.xml contains the new configuration for specified nodes.

The configuration of the submitted XML file must be the same obtained by the previous method "getNodeParameters".


Following attributes cannot be modified, thus system will skip them, even if the user tries to submit them.

  • node_id
  • zone_id
  • node_serial
  • node_last_change
  • node_last_updated
  • node_last_updating
  • node_last_connected

File management

(api/rest/file)


Upload a new file into the system

A new file can be uploaded into the system in the following way: 

	curl -F "login=@loginFile.xml" -F "upload=@fileToUpload.ext" "cms.mobitouchcube.com/api/rest/file?method=uploadFile"

The file to upload must be passed to the url with the "upload" key. Thus, option ' -F "upload=@..." ' is compulsory.

The system will accept ONE file at time, files must be smaller than 10 MB each.

When you upload a file, you receive a response XML like this: 

<Api_File generator="zend" version="1.0">
   <uploadFile>
      <file>
         <file_id>410</file_id>
         <folder_id>209</folder_id>
         <company_id>1</company_id>
         <file_name>birracheride</file_name>
         <file_ext>png</file_ext>
         <file_mime>image/png</file_mime>
         <file_hash_md5>2fb54bed8ce01327c54e99c2059cfd0c</file_hash_md5>
         <file_hash_sha1>9003c3cf4e8c54c54b22467cd3142e08581a4f0e</file_hash_sha1>
         <file_size>49007</file_size>
         <file_fullname>birracheride.png</file_fullname>
      </file>
      <status>success</status>
   </uploadFile>
</Api_File>

The response XML contains informations which can be useful when you want create a create a new campaign.In fact, you need a lot of information to create a new campaign and the informations included in this response XML are required when you perform a request for a new campaign.

NOTE:

  • All files uploaded through API will be saved into a folder of the repository named "API", which will be created if not present.
  • The "API" folder cannot be deleted from the system, even if it was empty.
  • Files into "API" folder can be used also from the standard web-based CMS.
  • If you execute the upload of the same file for two (or more) times, the system successfully performs the operation but it doesn't duplicate the file in the repository. The file will be overwritten and the same file_id will be kept. Nodes using the overwritten file will be notified.

Get a list of files uploaded on the system

	"method=getFiles"

Return ALL files belonging to user's company on the system


Delete a file from the system

	
"method=deleteFile&file_id=XX"

Deletes a file from the system, if the file is not used anywhere.

Campaign management

(/api/rest/campaign)

Get the list of campaigns defined for user's company

	"method=getCampaigns"

Retrieves all campaigns as XML.

A XML file containing all campaigns of your compant will be returned. 

<Api_Campaign generator="zend" version="1.0">
     <getCampaigns>
         <campaigns>
            <key_0>
                <campaign_id>1</campaign_id>
                <description>Campaign description</description>
                <enabled>1</enabled>
                <forward_url></forward_url>
            </key_0>
            <key_1>
                <campaign_id>7</campaign_id>
                <description>Another description</description>
                <enabled>1</enabled>
                <forward_url>http://www.someValidUrlForFileUpload.com</forward_url>
            </key_1>

            .......

         </campaigns>
         <status>1</status>
         <code>100</code>
     </getCampaigns>
</Api_Campaign>


Create a new campaign

	"method=createCampaign"

This method creates a new campaign, with at least one schedule and one content (simple).

The campaign just created will be returned as XML.

A long XML is required, with campaign basic settings, but also schedules and contents. The XML file for settings must be passed this way: 

	-F "campaign=@campaignFile.xml"


Here's an example of an input XML used to create a new campaign ("campaignFile.xml"): 

<campaign>
	<campaign_name>Test flo campaign API</campaign_name>
	<description>API API API</description>
	<enabled>1</enabled>
        <forward_url/>
	<schedules>
		<key_0>
			<schedule_id>209</schedule_id>
			<campaign_id>52</campaign_id>
			<crontab>* * * * 3,2,1</crontab>
			<duration>5</duration>
			<period_config>[-1,"* * * * 3,2,1","5"]</period_config>
			<description>Custom</description>
			<start_date>2009-10-01</start_date>
			<start_time>00:00</start_time>
			<end_date>2009-11-01</end_date>
			<end_time>23:59</end_time>
		</key_0>
		<key_1>
			<schedule_id>210</schedule_id>
			<campaign_id>52</campaign_id>
			<crontab/>
			<duration/>
			<period_config/>
			<description>Always</description>
			<start_date>2006-10-01</start_date>
			<start_time>00:00</start_time>
			<end_date>2015-11-01</end_date>
			<end_time>23:59</end_time>
		</key_1>
	</schedules>
	<contents>
		<key_0>
			<content_id>158</content_id>
			<campaign_id>52</campaign_id>
			<content_name>a content name 1</content_name>
			<description>your description</description>
			<policy_id>simple</policy_id>
			<twoway_match_string/>
			<files>
				<key_0>
					<file_id>410</file_id>
         				<folder_id>209</folder_id>
					<company_id>1</company_id>
					<file_name>birracheride</file_name>
					<file_ext>png</file_ext>
					<file_mime>image/png</file_mime>
					<file_hash_md5>2fb54bed8ce01327c54e99c2059cfd0c</file_hash_md5>
					<file_hash_sha1>9003c3cf4e8c54c54b22467cd3142e08581a4f0e</file_hash_sha1>
					<file_size>49007</file_size>
					<file_fullname>birracheride.png</file_fullname>
				</key_0>
			</files>
		</key_0>
		<key_1>
			<content_id>159</content_id>
			<campaign_id>52</campaign_id>
			<content_name>a content name 2</content_name>
			<description>write your descr here</description>
			<policy_id>simple</policy_id>
			<twoway_match_string/>
			<files>
				<key_0>
					<file_id>410</file_id>
         				<folder_id>209</folder_id>
					<company_id>1</company_id>
					<file_name>birracheride</file_name>
					<file_ext>png</file_ext>
					<file_mime>image/png</file_mime>
					<file_hash_md5>2fb54bed8ce01327c54e99c2059cfd0c</file_hash_md5>
					<file_hash_sha1>9003c3cf4e8c54c54b22467cd3142e08581a4f0e</file_hash_sha1>
					<file_size>49007</file_size>
					<file_fullname>birracheride.png</file_fullname>
				</key_0>
			</files>
		</key_1>
	</contents>
</campaign>

This Xml can be divided into 3 parts:

  • the 1st part (the lines that immediately follow the tag <campaign>) contains general informations about campaign.
  • the 2nd part (all the lines between the tag <schedules>) contains the scheduling informations needed by campaign.
  • the 3rd part (lines between <contents>) contains the contents informations of the campaign.

NOTE

  • If you try to create the same campaign for two times, the system creates two distinct campaign (with the same settings).
  • You cannot specify a campaign_id for this campaign nor the company_id owner of the campaign, these two parameters are automatically assigned by the system.

Set campaign basic details

	"method=setCampaignBasic&campaign_id=XX"

Campaign basic setting are modified, name, description, enabled (running or stopped).

Settings are in a XML file that must be passed this way: -F "campaign=@campaignFile.xml"

The file can be set this way: 

<campaign>
   <campaign_name>Basic campaign settings</campaign_name>
   <description>This is the campaign description</description>
   <enabled>1</enabled>
   <forward_url/>
</campaign>


NOTE

  • the campaign_id and the company_id are not editable


Get current schedules for a campaign

	"method=getCampaignSchedules&campaign_id=XX"

Returns an XML containing all schedules for specified campaigns.


Set new schedules for a campaign

 	"method=setCampaignSchedules&campaign_id=XX"

Sets new schedules for specified campaign, all the old ones will be removed. Schedules are in an XML file that must be passed this way: 

  	-F "schedules=@schedulesFile.xml"

This XML file has the same structure as the one returned by "getCampaignSchedules", but only <schedules> tag.

It's not necessary to provide a campaign_id for each schedule. The system itself will set it properly.

If campaign_id is set, it will be skipped.

Get current contents for a campaign

	
	"method=getCampaignContents&campaign_id=XX"

Returns all defined contents for specified campaign.


Set new contents for a campaign

	"method=setCampaignContents&campaign_id=XX"

Sets new contents for specified campaign, all the old ones will be removed. Contents are in an XML file that must be passed this way: 

-F "contents=@contentsFile.xml"

This XML file has the same structure as the one returned by "getCampaignContents", but only <contents> tag.

Only "simple" policies for contents can be set.

Here's an example of a contentsFile.xml : 

<contents>
	<key_0>
		<content_name>contenuto cappero</content_name>
		<description>la marianna va in campagna</description>
		<policy_id>simple</policy_id>
		<twoway_match_string/>
		<files>
			<key_0>
				<file_id>411</file_id>				
				<folder_id>209</folder_id>
				<company_id>1</company_id>
				<file_name>logoPeroni</file_name>
				<file_ext>png</file_ext>
				<file_mime>image/png</file_mime>
				<file_hash_md5>e90a5fdf79beaceab25b239d36462a27</file_hash_md5>
				<file_hash_sha1>b6bbaa89f6c731051700fdadbc1eca61809128b0</file_hash_sha1>
				<file_size>25023</file_size>
				<file_fullname>logoPeroni.png</file_fullname>
			</key_0>
		</files>
	</key_0>
</contents>

The system will take care of setting proper content_id and campaign_id to each content.

Different values explicitly set will be skipped.

Get a list of node ids of the nodes currently associated to a campaign 

	"method=getCampaignNodes&campaign_id=XX"

Returns a list of node ids for the specified campaign.

Set new node ids for a campaign 

	"method=setCampaignNodes&campaign_id=XX"

Sets new nodes for specified campaign, all the old ones will be dissociated.

Node ids are in an XML file that must be passed this way: 

-F "nodes=@nodesFile.xml"

This XML file has the same structure as the one returned by "getCampaignNodes", but only <nodes> tag and its contents.

Both previouly associated nodes and new nodes are automatically notified of the change.

Tutorial: Create a fortune cookie campaign

In this chapter, we'll try to create a campaign that use the *nix command "fortune" to auto-generate a random text content.

These are the desidered parameters for this campaign:

  • a pediocity of 6 minutes
  • the message receveid every six minutes must be different than the previous message

We recommend to create a tree directory like this: 

fortuneFolder
   |
   +-->XML
   |    |
   |    +--> login.xml
   |    |
   |    +--> myNode.xml
   |
   +-->TXT
   |    |
   |    +--> newCampaignXML_part1 
   |    |
   |    +--> newCampaignXML_part2
   |
   +--> uploadFortune.sh
   |
   +--> assignNodetoCampaign.sh
   |
   +--> composeXml.sh
   |
   +--> createCampaign.sh

First, we upload a file on system. Later we create a content and a campaign and assign a node to it.

Finally , we set a crontab timer to update periodically the content of txt file.

Note:

  • the node used in this tutorial has a "Server synchronization frequency" of 5 minutes.

Set the login Xml

You need to set your credential to use API methods.

We store these information in a Xml file : login.xml in the XML folder. Every script uses login.xml to authenticate on the system.

login.xml: 

<login>
  <username>myUsername</username>
  <password>myPassword</password>
</login>

Upload a "random" file

uploadFortune.sh  : 

#!/bin/bash

SCRIPT_DIR=/home/flo/fortuneFolder

LOGIN_XML="${SCRIPT_DIR}/XML/login.xml"
FORTUNE_TXT="${SCRIPT_DIR}/TXT/fortune.txt"
RESPONSE_XML="${SCRIPT_DIR}/XML/responseUpload.xml"


/usr/games/fortune >$FORTUNE_TXT 

/usr/bin/curl -F "login=@$LOGIN_XML" "cms.mobitouchcube.com/api/rest/file?method=uploadFile" -F "upload=@$FORTUNE_TXT" > $RESPONSE_XML

The script uses fortune to create random sentences and redirects the output in a FORTUNE_TXT file.

Then it sends the file to the system via curl and saves the response file into RESPONSE_XML.


Note:

  • you MUST set SCRIPT_DIR according to the path of script directory on your local machine (my pah is "/home/flo/fortuneFolder" ).

Compose XML to create a new campaign

Once we uploaded the TXT FILE, we need to create an Xml file that describes the new campaign.

We do this with composeXml.sh: 

SCRIPT_DIR=$(pwd)
LOGIN_XML="${SCRIPT_DIR}/XML/login.xml"
PART_1="${SCRIPT_DIR}/TXT/newCampaignXML_part1"
PART_2="${SCRIPT_DIR}/TXT/newCampaignXML_part2"
FILE_XML="${SCRIPT_DIR}/XML/responseUpload.xml"
NEW_CAMPAIGN_XML="${SCRIPT_DIR}/XML/newCampaign.xml"



sed -e 's/<?.*$//' -e 's/<Api.*<uploadFile><file>//' -e 's/<\/file><status.*$//' $FILE_XML >tmp.XML
cat $PART_1 tmp.XML $PART_2 > $NEW_CAMPAIGN_XML
rm tmp.XML

This script creates an Xml file merging the contents of responseUpload.xml (created by uploadFortune.sh), newCampaignXML_part1 and newCampaignXML_part2.


newCampaignXML_part1 : 

<campaign>
	<campaign_id>1</campaign_id>
	<company_id>1</company_id>
	<campaign_name>Fortune Cookie</campaign_name>
	<description>this campaign sends a fortune cookie every six minutes</description>
	<enabled>1</enabled>
	<schedules>
		<key_0>
			<schedule_id>224</schedule_id>
			<campaign_id>1</campaign_id>
			<crontab>2,8,14,20,26,32,38,44,50,56 * * * *</crontab>
			<duration>2</duration>
			<period_config>[-1,"2,8,14,20,26,32,38,44,50,56 * * * *",2]</period_config>
			<description>Custom</description>
			<start_date>2008-10-17</start_date>
			<start_time>00:00</start_time>
			<end_date>2009-10-18</end_date>
			<end_time>00:00</end_time>
		</key_0>
	</schedules>
	
	<contents>
		<key_0>
			<content_id>158</content_id>
			<campaign_id>1</campaign_id>
			<content_name>simple txt file</content_name>
			<description>your description</description>
			<policy_id>simple</policy_id>
			<twoway_match_string/>
			<files>
				<key_0>

In newCampaignXML_part1 you must manually set the value of company_id tag with your company ID. If you don't know your company ID, you can find it in responseUpload.xml .

responseUpload.sh: 


<Api_File generator="zend" version="1.0">
  <uploadFile>
    <file>
      <file_id>412</file_id>
      <folder_id>209</folder_id>
      <company_id>1</company_id>
      <file_name>fortune</file_name>
      <file_ext>txt</file_ext>
      <file_mime>text/plain; charset=us-ascii</file_mime>
      <file_hash_md5>2e806a761e90f0ada40bf150a5e9e79e</file_hash_md5>
      <file_hash_sha1>2ab41d11b7c39f78a7de073d7f72a15c1aacf5a1</file_hash_sha1>
      <file_size>74</file_size>
      <file_fullname>fortune.txt</file_fullname>
    </file>
    <status>1</status>
    <code>100</code>
  </uploadFile>
</Api_File>

newCampaignXML_part2 : 

				</key_0>
			</files>
		</key_0>
	</contents>
</campaign>


The resulting xml is newCampaign.xml : 

<campaign>
	<campaign_id>1</campaign_id>
	<company_id>1</company_id>
	<campaign_name>Fortune Cookie</campaign_name>
	<description>this campaign sends a fortune cookie every six minutes</description>
	<enabled>1</enabled>
	<schedules>
		<key_0>
			<schedule_id>224</schedule_id>
			<campaign_id>1</campaign_id>
			<crontab>2,8,14,20,26,32,38,44,50,56 * * * *</crontab>
			<duration>2</duration>
			<period_config>[-1,"2,8,14,20,26,32,38,44,50,56 * * * *",2]</period_config>
			<description>Custom</description>
			<start_date>2008-10-17</start_date>
			<start_time>00:00</start_time>
			<end_date>2009-10-18</end_date>
			<end_time>00:00</end_time>
		</key_0>
	</schedules>
	
	<contents>
		<key_0>
			<content_id>158</content_id>
			<campaign_id>1</campaign_id>
			<content_name>simple txt file</content_name>
			<description>your description</description>
			<policy_id>simple</policy_id>
			<twoway_match_string/>
			<files>
				<key_0>
                                 <file_id>412</file_id>
                                 <folder_id>209</folder_id>
                                 <company_id>1</company_id>
                                 <file_name>fortune</file_name>
                                 <file_ext>txt</file_ext>
                                 <file_mime>text/plain; charset=us-ascii</file_mime>
                                 <file_hash_md5>a3efa5790f3538216a92403e457a164a</file_hash_md5>
                                 <file_hash_sha1>373526e24a1e0c61a3343b7559b868c79684b32d</file_hash_sha1>
                                 <file_size>65</file_size>
                                 <file_fullname>fortune.txt</file_fullname>
				</key_0>
			</files>
		</key_0>
	</contents>
</campaign>

Create the campaign

To create the campaign, ypu simply launch createCampaign.sh : 

#!/bin/bash
SCRIPT_DIR=$(pwd)

LOGIN_XML="${SCRIPT_DIR}/XML/login.xml"
FORTUNE_TXT="${SCRIPT_DIR}/TXT/fortune.txt"
RESPONSE_XML="${SCRIPT_DIR}/XML/responseCampaign.xml"
CAMPAIGN_XML="${SCRIPT_DIR}/XML/newCampaign.xml"


/usr/bin/curl -F "login=@$LOGIN_XML" "cms.mobitouchcube.com/api/rest/campaign?method=createCampaign" -F "campaign=@$CAMPAIGN_XML" >$RESPONSE_XML

Now we need to deploy a campaign on a node.

Deploy the campaign on a node

assignNodeToCampaign.sh deploy Fortune Cookie Campaign on a node: 

#!/bin/bash
SCRIPT_DIR=$(pwd)

LOGIN_XML="${SCRIPT_DIR}/XML/login.xml"
CAMPAIGN_RESPONSE_XML="${SCRIPT_DIR}/XML/responseCampaign.xml"
RESPONSE_XML='responseAssign.xml'
MY_NODE_XML="${SCRIPT_DIR}/XML/myNode.xml"

CAMPAIGN_ID=$(sed -e '/<?.*$/d' -e 's/.*<campaign_id>//' -e 's/<\/campaign_id>.*$//'  $CAMPAIGN_RESPONSE_XML )
curl -F "login=@$LOGIN_XML" "cms.mobitouchcube.com/api/rest/campaigns?method=setCampaignNodes&campaign_id=$CAMPAIGN_ID" -F "nodes=@$MY_NODE_XML" > $RESPONSE_XML

Before launch this script , you need to set the node id in myNode.xml: 

<nodes>
   <node0>133</node0>
</nodes>

A simple way to know your node id is get the list of your nodes.

Set a CRON timer

Finally we set CRON to refresh the content of fortune.txt.

Type "crontab -e" to edit your CRON file.

add this line to your file: 

*/6 * * * * /home/flo/fortuneFolder/uploadFortune.sh

you must correctly set the path of uploadFortune.sh.

Now you have a campaign with a new random content every six minutes.

Retrieved from "http://help.mobitouchcube.com/API_Interfacing"