This document describes how to configure, connect to, and interact with the API. For information on expanding the API with your own custom code see Extending the API. All examples are presented using PHP.

Configuration

Before you begin using the API you must first create a set of API credentials for the company you wish to connect to. For information on creating API credentials check the API section of the User Manual.

Overview

Structure

The structure of an API request involves specifying the model, method, and format to be requested, along with any additional parameters the method may require. For example:

https://yourdomain.com/installpath/index.php/api/users/get.xml?user_id=1

In the above example, yourdomain.com is your domain and installpath is the path to the Blesta installation. If you have enabled pretty URLs in Blesta the path omit the index.php portion. users is the model to request, get is the method, and xml is the format.

Formats

The API supports XML, JSON, and PHP serialization formats. By default XML formatting is used. So if there is an error detecting the format of the request (due to a bad URL, for example) the error response will be returned in XML format.

Errors

Timestamps

The API returns all timestamps in UTC time using the following ISO 8601 format:

YYYY-MM-DD hh:mm:ss / 2021-12-31 12:00:00

The API expects timestamps in one of the following formats:

YYYY-MM-DD hh:mm:ss ±hh:mm / 2021-12-31 12:00:00 +00:00
YYYY-MM-DD hh:mm:ss UTC / 2021-12-31 12:00:00 UTC
YYYY-MM-DDThh:mm:ssZ / 2021-12-31T12:00:00Z

Authentication

The API supports Basic Authentication.

Connecting

There are a number of ways to connect to the API. Choose the option that best fits your environment.

Remotely

To connect remotely, first determine the URL of the API for your installation. The default path is http://yourdomain.com/installpath/index.php/api/. Where yourdomain.com is the domain you've installed Blesta in, and installpath is the path to Blesta. If you have enabled pretty URLs in Blesta the path may exclude index.php, and instead appear as http://yourdomain.com/installpath/api/.

Because requests may contain sensitive information, you should only process requests remotely over a secure connection (i.e. only use HTTPS).

The following example illustrates how to connect to the API using cURL.

<?php
// The URL to the API
$api_url = "https://yourdomain.com/installpath/index.php/api/";

// API credentials
$api_username = "username";
$api_key = "key";

// The Model to request
$model = "users";
// The method to request
$method = "get";
// The response format
$format = "xml";

// All parameters to send
$params = array(
 'user_id'=>1
);


$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url . $model . "/" . $method . "." . $format . "?" . http_build_query($params));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $api_username . ":" . $api_key);

$result = curl_exec($ch);
echo $result;
?>

Locally

Using the Command Line Interface

The API is available via a command line interface (CLI). The API supports the following command line parameters:

1. -u or -user The API user
2. -k or -key The API key
3. -m or -method The method for the quest (GET, POST, PUT, DELETE)
4. -p or -params A serialized array of paramters as you would find in a URL string (e.g. first_name=John&last_name=Doe&company=Acme Co.)

Below is an example API requests.

php index.php /api/users/get.xml -u USER -k KEY -p "user_id=1"

Within the Blesta environment

If you're working with or have created code within the Blesta environment, there's no need to use the API at all. All of the methods available in the API are first and foremost available to Blesta, in the form of models. To use these models, simply load the model within your environment.

// from somewhere in your controller...
$this->uses(array("ModelName"));

// Now invoke it
$this->ModelName->someMethod($param1, $param2);

// from any other class...
Loader::loadModels($this, array("ModelName"));

// Now invoke it
$this->ModelName->someMethod($param1, $param2);

Requests

The API supports hundreds of requests.

-k or -key The API key