API

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 consult the API Access 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.json?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 omit the index.php portion. users is the model to request, get is the method, and json is the format.

Formats

The API supports XML, JSON, and PHP serialization formats. By default JSON 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 JSON format.

Errors

There are several types of errors that may be encountered when working with the API:

1. Sending invalid parameters will result in a 400 Bad Request response.

   HTTP/1.1 400 Bad Request
   Content-Length: 161
   
   {
    "model":
    {
     "message":"The request cannot be fulfilled due to bad syntax.",
     "errors":
     {
      "field":
      {
       "code":"Error message."
      }
     }
    }
   }

2. Providing invalid credentials will result in a 401 Unauthorized response.

   HTTP/1.1 401 Unauthorized
   Content-Length: 67
   
   {"message":"The authorization details given appear to be invalid."}

3. Attempting to access a resource that is not callable will result in a 403 Forbidden response.

   HTTP/1.1 403 Forbidden
   Content-Length: 55
   
   {"message":"The requested resource is not accessible."}

4. Attempting to access a resource that does not exist will result in a 404 Not Found response.

   HTTP/1.1 404 Not Found
   Content-Length: 52
   
   {"message":"The requested resource does not exist."}

5. Requesting a format that is not supported will result in a 415 Unsupported Media Type response.

   HTTP/1.1 415 Unsupported Media Type
   Content-Length: 66
   
   {"message":"The format requested is not supported by the server."}

6. If an unexpected error occurs a 500 Internal Server Error will result. If this error is encountered consult the documentation for the method you are requesting.

   HTTP/1.1 500 Internal Server Error
   Content-Length: 42
   
   {"message":"An unexpected error occured."}

7. When Blesta is under maintenance mode, the API will return a 503 Service Unavailable response.

   HTTP/1.1 503 Service Unavailable 
   Content-Length: 81 
   
   {"message":"The requested resource is currently unavailable due to maintenance."}

All error response objects contain an array of input parameters that produced errors. From the example above "field" is the parameter name. Each field may contain one or more error codes along with a related message. Common codes are empty, exists, format, length, and valid, but many more are available. The error code is always the index of the error message, and is used primarily in identifying the type of error encountered.

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 for web requests. When connecting to the API via a command line the API credentials must be passed as parameters. See API#Using the Command Line Interface for more information on connecting to the API via command line.

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 configured your installation to omit index.php from URLs then the URL should 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 = "json";

// 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 request (GET, POST, PUT, DELETE)
4. -p or -params A URL encoded array of parameters as you would find in a URL string (e.g. first_name=John&last_name=Doe&company=Acme Co.)

Below is an example API request.

php index.php /api/users/get.json -u USER -k KEY -m GET -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.