Gateway API Methods
NOTE: It is recommended to upgrade your Gateway to software version 1.1 before attempting to use the API. This documentation applies to API v. 1.1.
The Gateway API is a JSON Extend API similar to the Switchvox XML Extend API, in which methods are called via an HTTPS request and the Gateway returns a JSON-encoded response. A client's first HTTPS request will log into the Gateway, which will return an authentication cookie which must be presented in each subsequent request. Please see the examples.
General information
Authentication
Authentication is performed via a simple HTTPS request to https://192.168.69.1/admin/main.html. 192.168.69.1 is the default IP, and this must be replaced with your Gateway appliance's IP address or hostname if you are not using the default IP address. To authenticate, simply POST to this URL on your Gateway, sending the authentication credentials as parameters named 'admin_uid', 'admin_password'. The webserver on the Gateway will set a cookie you can use to authenticate on subsequent responses.
The API, in the same way as the administration interface, is only available via HTTPS. If you are using the self-signed certificate which comes with the Gateway or another certificate signed by a smaller certificate authority, you may need to disable hostname verification. Your requests and responses will still be encrypted, and you will not receive an error if the certificate authority's cert bundle cannot be located. See Example Perl Script - List Information and Shutdown for instructions in Perl. This has not been a problem for me with Python's mechanize.Request().
Perl Authentication Example
If you are using LWP for the HTTPS requests, LWP::Protocol::https and all its dependencies are requirements.
use LWP::UserAgent;
# included by LWP as well, this is only here so the script
# throws an error if this dependency of HTTPS + LWP is unmet.
use LWP::Protocol::https;
use HTTP::Cookies;
my $ua = new LWP::UserAgent;
my $cookies = new HTTP::Cookies();
$ua->cookie_jar($cookies);
my $response = $ua->post("https://$GATEWAY_IP/admin/main.html", {
admin_uid => $USERNAME,
admin_password => $PASSWORD
});
my $content = $response->content;
if ($content !~ m/Welcome,\s+$USERNAME/i || $content !~ m/Log Out/i) {
print "Login Failed!\n";
print "$content\n";
exit 1;
}
|
Python Authentication Example
data = {
'admin_uid': gateway_user,
'admin_password': gateway_pass
}
data_str = '&'.join(['%s=%s' % (k,v) for k,v in data.iteritems()])
req = mechanize.Request("https://%s/admin/main.html" % gateway_ip, data_str)
cj = cookielib.LWPCookieJar()
cj.add_cookie_header(req)
res = mechanize.urlopen(req)
lines = res.read()
if re.search("Welcome,\s+%s" % gateway_user, lines) is None:
print "Login Failed!"
print lines
return 1
|
Methods
*_list
Input:
name
value type
required
object_name
the 'name' parameter of the object
yes, if no object_id specified
object_type
the type of object as defined by the backend
no
object_id
integer representing the auto-increment field from the database
yes, if no object_name specified
Output: JSON element as defined for each method
*_save
Input: JSON element as defined for each method
Output:
name
value type
required
result
'failure' or 'success'
yes
error
string
no
error_key
language key
no
*_delete
Input:
name
value type
required
object_name
the 'name' parameter of the object
yes, if no object_id specified
object_type
the type of object as defined by the backend
no
object_id
integer representing the auto-increment field from the database
yes, if no object_name specified
Output:
name
value type
required
result
failure' or 'success'
yes
error
string
no
error_key
language key
no
Storing Custom Data and Reserved Keywords
The Gateway API gives users the ability to store custom data as attributes of the API objects on the Gateway for later retrieval. This information will not affect the configuration of the Gateway but can be used to save notes and information only applicable to the developer. The Gateway API relies on many keywords to maintain the integrity of the data it deals with. Please see the API documentation for the methods and objects in question as you are developing and take care not to use any key listed there or here in the list of globally reserved keywords.
Reserved keywords:
istemplate
hastemplate
isinclude
object_name
object_id
object_type