Gateway API Methods

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

Configuration

SIP Endpoints

Advanced SIP Settings

T1/E1 Settings

Call Routing Groups

Call Routing Rules

System Administrators

IP Configuration

Access Control

Reporting

Statistics

Remote Logging

Diagnostics

Connection Status

System Information

Diagnostic Tests

Advanced Debugging

Technical Support

Maintenance

Backups and Templates

Certificates and Keys

Software Updates

System Clock

System Reset

 

Return to Documentation Home I Return to Sangoma Support