Building a Web Services API with Elgg

Elgg provides an API for building custom web services. You expose functionality through the web services API by building a plugin and then either publish your API for other developers to build clients or provide your own. Here is a simple example of exposing a method so that a client app can post a status update to the wire in Elgg:

1. Write your function that creates the wire post

function rest_wire_post($username, $text) {
    $user = get_user_by_username($username);
    if (!$user) {
        throw new InvalidParameterException('Bad username');
    }

    $obj = new ElggObject();
    $obj->subtype = 'thewire';
    $obj->owner_guid = $user->guid;
    $obj->access_id = ACCESS_PUBLIC;
    $obj->method = 'api';
    $obj->description = elgg_substr(strip_tags($text), 0, 140);

    $guid = $obj->save();

    add_to_river('river/object/thewire/create',
                 'create',
                 $user->guid,
                 $obj->guid
                );

    return 'success';
}


2. Expose it

expose_function('wire.post',
                'rest_wire_post',
                array( 'username' => array ('type' => 'string'),
                       'text' => array ('type' => 'string'),
                     ),
                'Post a status update to the wire',
                'GET',
                false,
                false);


3. Use it

Type this into your browser's address bar making the obvious replacements for your site:

http://mysite.com/services/api/rest/xml/?method=wire.post&username=cash&text=hello

Now, in a real application you would make this a POST request rather than a GET and protect it with user and API authentication. For more information on that see the Elgg web services wiki page.

4 Comments

What files in the engine do you insert the functions rest_wire_post() and expose_function()? Their documentation doesn't specify ideal places to insert these functions.

The start.php of each plugin can be thought of as the boot loader of the plugin. You can put web services functions in it or you can include a separate file with the web services functions using start.php.

You should never need to edit any files in the engine.

The typical approach for registering the functions through expose_function() is on the init, system event. There is some documentation on events here: http://docs.elgg.org/wiki/Events_Overview

In http://blog.elgg.org/pg/blog/dave/read/160/a-foundation-acquisition-and-change speaking of a new Elgg book written by Cash. Where I can look it up? Greetings

The publisher should be making an announcement soon. We'll be sure to mention it on the Elgg blog. I expect it will be available sometime in the February to March time frame. Thanks for asking.

Leave a comment

Recent Entries

  • Building a Web Services API with Elgg

    Elgg provides an API for building custom web services. You expose functionality through the web services API by building a plugin and then either publish...

  • Session security and Chrome Frame

    I've run into the nasty problem that Chrome Frame causes to session handling code that uses the user agent in its security. There are applications...

  • Piwik and Elgg

    While Google Analytics may be the most popular analytics service, there are times when you want to use your own hosted solution (intranet, control over...

  • Piwik and Reverse Proxy

    Piwik generates its URLs used in links and forms based on data in $_SERVER[]. If you are using a reverse proxy in front of your...

  • Elgg Unit Tests

    A new component in Elgg 1.7 will be a unit test framework (SimpleTest). I've written a skeleton example of how plugin authors can use the...

Close