gift

SOAP Web Service API for Mobile Apps

Introduction

IBuildApp provides SOAP Web Service API that allows you to create, retrieve, update or delete content such as photos, news, or events. The web service description is available at https://ibuildapp.com/api/soap.wsdl.

We recommend that you download a SOAP client that can access and interact with SOAP-based service.

PHP developers may use the PHP SOAP extension:

require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl",
	array('classmap' => APIGlobal::$classmap )); 

Once SOAP client is initiated, you may call a function from the Web service (see HowTo). Web service transfers string data in UTF-8 format.

All API requests require private key (apiSecret). You can download it from App management page.

The API secret key value is the same and unique for each application.

To make a call using PHP, you can use APIMessage, APIParam, or APIItem classes. Those classes are described in APITypes.php file. The objects might be represented as associative array (see asArray functions).


Getting started: list of functions

To get started, you need to receive a list of functions assigned to the app: use getFunctions function that returns list of available SOAP functions. Specify the API Secret Key (apiSecret) that defines the app, as an argument.

PHP Example:
 APIGlobal::$classmap));
try {     
	$api_secret ='your apiSecret key';
	$result = $client->getFunctions(new APIMessage(new APIParam('apiSecret', $api_secret)));
	print_r( $result->asArray('item'));
} catch (SoapFault $e) {
	print $e->faultcode.' - '.$e->faultstring; 
}
Result:
Array (
   [101] => Array ([id] => 1 [controlId] => 2 [title] => GoogleMap [type] => map)
   [102] => Array ([id] => 2 [controlId] => 3 [title] => Image Gallery [type] => photo)      
   [103] => Array ([id] => 3 [controlId] => 4 [title] => Media [type] => media)      
   [104] => Array ([id] => 4 [controlId] => 5 [title] => E-book [type] => ebook)      
   [107] => Array ([id] => 5 [controlId] => 6 [title] => Events [type] => events)      
   [108] => Array ([id] => 5 [controlId] => 6 [title] => News [type] => news)      
)

You can get a function identifier (id) by page title or by function type.

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Photo Gallery

Retrieving list of images

Use the getFunctionParams API call to retrieve the list of images from the photo gallery. For the request, you specify the following arguments:

  • apiSecret key (mandatory) - private key for the app;
  • functionId (mandatory) - the function identifier, returned by getFunctions API call.

The full list of values returned by this function can be found in the documentation.

PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array('classmap' => APIGlobal::$classmap ));
try {
	$api_secret = 'your apiSecret key';
	$result = $client->getFunctionParams( new APIMessage(new APIParam('apiSecret', $api_secret), new APIParam('functionId', 102)));
	print_r( $result->asArray('param'));     
	print_r( $result->asArray('item')); 
} catch (SoapFault $e) {
	print $e->faultcode.' - '.$e->faultstring; 
}
Result:
Array (
	[functionId] => 102
	[title] => Image Gallery
	[backgroundColor] => #eb9be3
	[rssurl] => http://api.flickr.com/services/feeds/groups_discuss.gne?id=1803969@N22&lang=en-us&format=rss_200
	[useSource] => manual 
) 
Array (
	[1021] => Array
	(
		[id] => 1021
		[order] => 1
		[photoCaption] => Photo #1
		[photoDescription] => Photo #1 description
		[photoFile] => https://ibuildapp.com/assets/photos/7-493-1329296573.png
	) 
)

Image descriptions are stored in the item array. Each image is defined by id, title (photoCaption) and description (photoDescription). Image identifier (id) may be used for updating or removing the image (see updateFunctionParamItem and deleteFunctionParamItem API calls).

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Adding images

addFunctionParamItem API call will add a new image into the gallery. For each request, you specify the following arguments:

  • apiSecret key (mandatory);
  • functionId (mandatory) - function identifier, returned by getFunctions API call;
  • photoCaption (mandatory) - the image caption;
  • photoDescription (optional) - the image description;
  • photoFileUrl or photoFileData: if the image is located on a server, the URL (photoFileURL) parameter is required; if the image is stored on your local machine, you encode it into Base64 and then specify the base64-encoded string in photoFileData parameter.

PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array('classmap' => APIGlobal::$classmap ));
try {
    $api_secret = 'your apiSecret key';
    $result = $client->addFunctionParamItem(new APIMessage(new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 102),
		new APIParam('photoCaption', 'New Photo Caption'),
		new APIParam('photoFileUrl', 'http://example.com/upload/123.jpg')
    ));
    print_r( $result->asArray('param')); 
} catch (SoapFault $e) {
    print $e->faultcode.' - '.$e->faultstring; 
}
Result:
Array (
    [id] => 1022
)

The function returns the new image id in param array.

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Deleting Images

deleteFunctionParamItem API call will remove an image from the photo gallery. For each request, you specify the following arguments:

  • apiSecret key (mandatory);
  • functionId (mandatory) - function identifier, returned by getFunctions API call;
  • id (mandatory) - the image identifier, returned by getFunctionParams API call.
PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array('classmap' => APIGlobal::$classmap ));
try {
    $api_secret = 'your apiSecret key';
    $client->deleteFunctionParamItem(new APIMessage(new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 102),
		new APIParam('id', 1021)
    )); 
} catch (SoapFault $e) {
    print $e->faultcode.' - '.$e->faultstring;
}

The function doesn't return any value.

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Events

Retrieving Event List

Use the getFunctionParams API call to retrieve the list of events. For the request, you specify the following arguments:

  • apiSecret key (mandatory) - private key for the app;
  • functionId (mandatory) - the function identifier, returned by getFunctions API call.

The full list of values returned by this function can be found in the documentation.

PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array('classmap' => APIGlobal::$classmap ));
try {
	$api_secret = 'your apiSecret key';
	$result = $client->getFunctionParams( new APIMessage(
		new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 107)     ));
	print_r( $result->asArray('param'));
	print_r( $result->asArray('item')); 
	} catch (SoapFault $e) {
		print $e->faultcode.' - '.$e->faultstring; 
}
Result:
Array (
	[functionId] => 107
	[title] => Events
	[backgroundColor] => #eb9be3
	[textColor] => #850000
	[rssurl] => http://bash.org.ru/rss
	[useSource] => manual ) 
Array (
	[1071] => Array
	(
		[id] => 1071
		[order] => 3
		[eventDate] => 03/01/2012 06:00 pm
		[eventName] => Event #1
		[eventDescription] => Event #1 description
	)  )

Event descriptions are stored in the item array.

Each event is defined by it's id, title (eventName), date (eventDate), and description (eventDescription).

Event identifier (id) may be used for updating or removing the event (see updateFunctionParamItem and deleteFunctionParamItem API calls)

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Adding Events

addFunctionParamItem API call will post a new event. For each request, you specify the following arguments:

  • apiSecret key (mandatory);
  • functionId (mandatory) - function identifier, returned by getFunctions API call;
  • eventDate (mandatory) - event date, MM/DD/YYYY hh:mm am|pm formatted;
  • eventName (mandatory) - event name;
  • eventDescription (mandatory) - event description.
PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array(
    'classmap' => APIGlobal::$classmap )); 
try {
	$api_secret = 'your apiSecret key';
	$result = $client->addFunctionParamItem( new APIMessage(
		new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 107),
		new APIParam('eventName', 'Events #2'),
		new APIParam('eventDescription', 'Events #2 description'),
		new APIParam('eventDate', '03/24/2012 06:00 pm')
    ));
    print_r( $result->asArray('param')); 
} catch (SoapFault $e) {
	print $e->faultcode.' - '.$e->faultstring; 
}
Result:
Array (
     [id] => 1072
)

The function returns the new event id in param array.

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Deleting Events

deleteFunctionParamItem API call will remove an event. For each request, you specify the following arguments:

  • apiSecret key (mandatory);
  • functionId (mandatory) - function identifier, returned by getFunctions API call;
  • id (mandatory) - event identifier, returned by getFunctionParams API call.
PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array(
	'classmap' => APIGlobal::$classmap )); 
try {
	$api_secret = 'your apiSecret key';
	$client->deleteFunctionParamItem( new APIMessage(
		new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 107),
		new APIParam('id', 1071)
    )); 
} catch (SoapFault $e) {
	print $e->faultcode.' - '.$e->faultstring; 
}

The function doesn't return any value.

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


News

Retrieving News List

Use the getFunctionParams API call to retrieve the list of news. For the request, you specify the following arguments:

  • apiSecret key (mandatory) - private key for the app;
  • functionId (mandatory) - the function identifier, returned by getFunctions API call.

The full list of values returned by this function can be found in the documentation.

PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array(
    'classmap' => APIGlobal::$classmap )); 
try {
	$api_secret = 'your apiSecret key';
	$result = $client->getFunctionParams( new APIMessage(
		new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 108)
	));
	print_r( $result->asArray('param'));
	print_r( $result->asArray('item')); 
} catch (SoapFault $e) {
	print $e->faultcode.' - '.$e->faultstring; 
}
Result:
Array (
	[functionId] => 108
	[title] => News
	[backgroundColor] => #b0fcde
	[textColor] => #850000
	[rssurl] => https://ibuildapp.com/feed/
	[useSource] => manual 
)
Array (
	[1081] => Array
	(
		[id] => 1081
		[order] => 3
		[newsTitle] => News #1
		[newsContent] => News #1 content
		[newsDate] => 03/01/2012 06:00 pm
		[newsImage] => https://ibuildapp.com/assets/data/00000/0/000/images/1330414277.jpg
	)
)

News descriptions are stored in the item array.

Each news is defined by it's id, title (newsTitle), date/time, and description (newsContent). News identifier (id) may be used for updating or removing the news (see updateFunctionParamItem and deleteFunctionParamItem API calls)

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Adding News

addFunctionParamItem API call will post a news. For each request, you specify the following arguments:

  • apiSecret key (mandatory);
  • functionId (mandatory) - function identifier, returned by getFunctions API call;
  • newsDate (mandatory) - news date, MM/DD/YYYY hh:mm am|pm formatted;
  • newsTitle (mandatory) - news name;
  • newsContent (mandatory) - news description.
  • newsImageUrl or newsImageData (optional): if the image is located on a server, the URL (newsImageUrl) parameter is specified; if the image is stored on your local machine, you encode it into Base64 and then specify the Base64-encoded string in newsImageData parameter.
PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array(
	'classmap' => APIGlobal::$classmap )); 
try {
	$api_secret = 'your apiSecret key';
	$result = $client->addFunctionParamItem( new APIMessage(
		new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 108),
		new APIParam('newsTitle', 'News #2'),
		new APIParam('newsContent', 'News #2 content'),
		new APIParam('newsDate', '03/24/2012 06:00 pm'),
		new APIParam('newsImageUrl', 'http://yourdomain.com/123.jpg')
	));
	print_r( $result->asArray('param')); 
} catch (SoapFault $e) {
	print $e->faultcode.' - '.$e->faultstring; 
}
Result:
Array (
	[id] => 1082
)

The function returns the news id in param array.

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.


Deleting News

deleteFunctionParamItem API call will remove news post. For each request, you specify the following arguments:

  • piSecret key (mandatory);
  • functionId (mandatory) - function identifier, returned by getFunctions API call;
  • id (mandatory) - news identifier, returned by getFunctionParams API call.
PHP Example:
require_once 'APITypes.php'; 
$client = new SoapClient( "https://ibuildapp.com/api/soap.wsdl", array(
	'classmap' => APIGlobal::$classmap )); 
try {
	$api_secret = 'your apiSecret key';
	$client->deleteFunctionParamItem( new APIMessage(
		new APIParam('apiSecret', $api_secret),
		new APIParam('functionId', 108),
		new APIParam('id', 1081)    
	)); 
} catch (SoapFault $e) {
	print $e->faultcode.' - '.$e->faultstring; 
}

The function doesn't return any value.

If an error occurs during a SOAP request, the API returns a SoapFault message (SoapFault exception is handled by catch block). The faultstring property contains the error description.