00.getting.started.md

Getting Started

The CallFire API provides a robust interface to control functionality available through the regular web interface, plus some controls which are not otherwise accessible.

This library provides a set of PHP classes to interface with the CallFire API. Please refer to the API documentation for information on finding your API credentials.

If you are unable to utilize the Composer dependency management tool, please refer to Getting Started Without Composer.

There are two separate, but largely equivalent, endpoints by which you can access the CallFire API. These are the REST and SOAP APIs. Due to limitations in the PHP SOAP extension, you should largely aim to use the REST API, especially when interacting with the Broadcast services.

Both the SOAP and REST APIs share a common set of resources that they return, and share a set of operation "interfaces," but they are invoked differently. The benefit of these commonalities is that finding an issue with one API endpoint allows you to fall back to the other endpoint without too much difficulty.

The REST API

The REST API will be the primary API endpoint in our example documentation, because its design aims to make the structure of API requests more intuitive and stable.

Very basic example

This example demonstrates how to instantiate the REST API client, create a request object, invoke a request, and then parse the response into an easily-consumable form.

<?php
use CallFire\Api\Rest\Request;
require 'vendor/autoload.php';

$client = CallFire\Api\Client::Rest("<api-login>", "<api-password>", "Broadcast");

$request = new Request\QueryBroadcasts;
$response = $client->QueryBroadcasts($request);

$broadcasts = $client::response($response);

foreach($broadcasts as $broadcast) {
    var_dump($broadcast);
}

Though this code is fairly intuitive, there are a few clarifications to make.

First, each request is codified into a request object (a sort of "criteria object"). Any parameters in the request object that are left null will not be specified to the API. Not all operations require a request object, and some operations require additional parameters before the request object (e.g., a resource identifier). This cleanly separates required parameters from optional context-dependent parameters, to avoid confusion.

The return value from any given operation method is the unmodified response-body of the API request. This allows you to process the response in other ways, should you need to bypass this library's response parsing.

Responses

The $client::response() method is in fact a static method call to CallFire\Api\Rest\AbstractClient::response() that intuits the type of the response, then instantiates and populates an appropriate response object.

For methods that return lists of resources (e.g., QueryBroadcasts), this is a CallFire\Api\Rest\Response\ResourceList object. This object is an iterable set of resources (ordinarily all of the same type), such as CallFire\Common\Resource\Broadcast objects.

If an operation is returning a single resource, instead of several, then it will be parsed into a CallFire\Api\Rest\Response\Resource object, with which you can then call the getResource() method to obtain the actual resource.

It is also possible for an operation to return "exception" type responses, or nothing at all. Be sure to check the type of response that you are receiving to ensure that it's what you expect.

The SOAP API

Also available is the SOAP interface to the API. Due to some limitations of PHP's SOAP extension, it is not recommended that you use this portion of the SDK. Specifically, PHP's SOAP extension does not support the "anyAttribute" behaviour of the SOAP specification, which CallFire's services make use of for associating arbitrary metadata with contacts.

Very Basic Example

This example is equivalent to the same example for the REST client, but with some minor differences.

<?php
use CallFire\Api\Soap\Request;
require 'vendor/autoload.php';

$client = CallFire\Api\Client::Soap("<api-login>", "<api-password>", "Broadcast");

$request = new Request\QueryBroadcasts;
$response = $client->QueryBroadcasts($request);

$broadcasts = $client::response($response);

foreach($broadcasts as $broadcast) {
    var_dump($broadcast);
}

Obviously, the most fundamental change needed to be made to your code, relative to the REST client, is to change the namespace from which you construct request objects. As well, there is a separate helper method on the CallFire\Api\Client class to construct a SOAP client. In the case of this example, the code is otherwise equivalent.

Responses

The response format of a SOAP client call is slightly different from the response format of a REST client call. While the REST client will return to you the unmodified response data, the SOAP client will instead return a response object which is already constructed from the response data. Usually, this means that the $client::response() method will simply return to you the very same object that you passed in.

However, in API calls where you are creating a new resource in the CallFire system (e.g. Request\CreateBroadcast), the response is simply an integer. The $client::response() method will turn this into a Response\ResourceReference, for the purpose of interface compatibility with the REST client.

Similarly, when you are requesting an individual resource in the CallFire system (e.g. Request\GetBroadcast), the response will be the populated resource object. Passing this to the $client::response() method will create a Response\Resource.

In cases where a regular SoapClient would have thrown a SoapFault, this is instead caught and simply returned. The $client::response() method populates a Response\ResourceException for the purpose of interface compatibility with the REST client.