Utilities: Other: Programming API

The Programming API in ListManager works by fetching URLs in the ListManager web interface from within your program.

For example, if you use your web browser to go to http://localhost/utilities/other/api/test and click "submit" you will see the phrase "Test succeeded!".

Instead of using a web browser, you will want to use small programming scripts to fetch URLs that do actions you desire.

Examples in various programming languages

Below is source code for fetching the test URL in the ListManager web interface. These examples show how easy it is to have ListManager perform an action for you.

Linux Command Line

curl -u admin:lyris http://localhost/utilities/other/api/test_do
or
GET http://admin:lyris@localhost/utilities/other/api/test_do

Microsoft ASP

<% Response.Buffer = True
Dim objXMLHTTP, xml
Set xml = Server.CreateObject("Microsoft.XMLHTTP")
xml.Open "GET", "http://admin:lyris@localhost/utilities/other/api/test_do",
False
xml.Send ""
Response.Write xml.responseText
Set xml = Nothing %>

PHP

<?php
     function urlget ($url) {
           $f_page = @fopen ($url, "r");
           if ($f_page) {
                 $page_contents = fread ($f_page, 10240);
                 fclose ($f_page);
                 return ($page_contents);
           };
           return "";
     };
     print urlget("http://admin:lyris@localhost/utilities/other/api/test_do");
?>      

Python

import urllib
f = urllib.urlopen("http://admin:lyris@localhost/utilities/other/api/test_do")
print f.read()

How to find API functions

In order to make it easy for you to find and understand every Programming API function in ListManager, we have organized all the functions into menus, and each function has a very simple HTML form demonstrating what kind of information the function needs, and how that function works.

Passing Parameters

API functions can all be passed parameters in the URL, with the standard GET format (ie, setting=value on the URL) or alternatively, for larger amounts of data, all functions accept their parameters through the HTTP-POST standard (ie, as form POST variables).

Return Values

Most Programming API functions return just one value. In those cases the value is returned as raw text, as the HTML results of the URL.

If an error occurs and the API function cannot work, a text message is returned in this format:

<ERROR>sorry, an error occurred</ERROR>

Some API functions need to return a list of value, such as the function for "On what lists is a given email address?". In those cases a list of items is returned in this format:

<ITEM>first list item</ITEM>
<ITEM>second list item</ITEM>
<ITEM>third list item</ITEM>

If an API function needs to return a key/value array, such as the function for "Get all attributes of a member", then the results are returned in this format:

<KEY>first key</KEY><VALUE>first value</VALUE>
<KEY>second key</KEY><VALUE>second value</VALUE>
<KEY>third key</KEY><VALUE>third value</VALUE>

Security

The same security which the web interface enforces applies to the programming API as well. Thus, as a list administrator, you are allowed to access to all the member functions that you normally have access to in the GUI. If you try to work on a member from a list you don't have access to, an error will occur. Some API sections, such as the Server Config, SQL and List sections, require Server Administrator security rights.

All API functions are protected by an HTTP login. Whatever program you use to fetch URLs will need to pass a valid name and password when fetching the API URL (all the examples above do so). For example, in Perl this is accomplished with the command:

$req->authorization_basic('admin', 'lyris');

while in many other languages this is simply accomplished by adding username:password to the URL, like so:

http://username:password@hostname/utilities/other/api/test_do

If you are an administrator of a shared server, note that your list administrators do have access to a smaller set of the programming API, which includes most of the members API, so that they can program direct subscription management scripts.

Performance

The speed of most API functions is fast enough for most applications.

However, if you have bulk operations you need to accomplish, such as importing a member list, you should work directly with the SQL database that ListManager is using.