Elgg-Lorea-Hydra/docs/guides/web-services.rst

Web services
############

Build an HTTP API for your site.

Elgg provides a powerful framework for building web services. This
allows developers to expose functionality to other web sites and desktop
applications along with doing integrations with third-party web
applications. While we call the API RESTful, it is actually a REST/RPC
hybrid similar to the APIs provided by sites like Flickr and Twitter.

To create an API for your Elgg site, you need to do 4 things:

-  enable the web services plugin
-  expose methods
-  setup API authentication
-  setup user authentication

Additionally, you may want to control what types of authentication are
available on your site. This will also be covered.

.. contents:: Contents
   :local:
   :depth: 2

Security
--------

It is crucial that the web services are consumed via secure protocols. Do not
enable web services if your site is not served via HTTPs. This is especially
important if you allow API key only authentication.

If you are using third-party tools that expose API methods, make sure to carry
out a thorough security audit. You may want to make sure that API authentication
is required for ALL methods, even if they require user authentication. Methods that
do not require API authentication can be easily abused to spam your site.

Ensure that the validity of API keys is limited and provide mechanisms for your
API clients to renew their keys.

Exposing methods
----------------

The function to use to expose a method is ``elgg_ws_expose_function()``. As an
example, let's assume you want to expose a function that echos text back
to the calling application. The function could look like this

.. code:: php

    function my_echo($string) {
        return $string;
    }

Since we are providing this function to allow developers to test their
API clients, we will require neither API authentication nor user
authentication. This call registers the function with the web services
API framework:

.. code:: php

    elgg_ws_expose_function("test.echo", 
                    "my_echo", 
                     array("string" => array('type' => 'string')),
                     'A testing method which echos back a string',
                     'GET',
                     false,
                     false
                    );

If you add this code to a plugin and then go to
http://yoursite.com/services/api/rest/xml/?method=system.api.list, you
should now see your test.echo method listed as an API call. Further, to
test the exposed method from a web browser, you could hit the url:
http://yoursite.com/services/api/rest/xml/?method=test.echo&string=testing
and you should see xml data like this:

.. code:: xml

    <elgg>
        <status>0</status>
        <result>testing</result>
    </elgg>

Response formats
~~~~~~~~~~~~~~~~

The web services API framework provides three different response formats
by default: xml, json, and serialized php. You can request the different
formats for substituting “json” or “php” for “xml” in the above URLs.
You can also add additional response formats by defining new viewtypes.

Parameters
~~~~~~~~~~

Parameters expected by each method should be listed as an associative array, where the key represents the parameter name, and the value contains an array with ``type``, ``default`` and ``required`` fields.

Values submitted with the API request for each parameter should match the declared type. API will throw on exception if validation fails.

Recognized parameter types are:	

 - ``integer`` (or ``int``)
 - ``boolean`` (or ``bool``)
 - ``string``
 - ``float``
 - ``array``

Unrecognized types will throw an API exception.

You can use additional fields to describe your parameter, e.g. ``description``.

.. code:: php

    elgg_ws_expose_function('test.greet',
                    'my_greeting',
                    array(
                        'name' => array(
                            'type' => 'string',
                            'required' => true,
                            'description' => 'Name of the person to be greeted by the API',
                        ),
                        'greeting' => array(
                            'type' => 'string',
                            'required' => false,
                            'default' => 'Hello',
                            'description' => 'Greeting to be used, e.g. "Good day" or "Hi"',
                        ),
                    ),
                    'A testing method which greets the user with a custom greeting',
                    'GET',
                    false,
                    false
    );

API authentication
------------------

You may want to control access to some of the functions that you expose.
Perhaps you are exposing functions in order to integrate Elgg with
another open source platform on the same server. In that case, you only
want to allow that other application access to these methods. Another
possibility is that you want to limit what external developers have
access to your API. Or maybe you want to limit how many calls a
developer can make against your API in a single day.

In all of these cases, you can use Elgg's API authentication functions
to control access. Elgg provides two built-in methods to perform API
authentication: key based and HMAC signature based. You can also add
your own authentication methods. The key based approach is very similar
to what Google, Flickr, or Twitter. Developers can request a key (a
random string) and pass that key with all calls that require API
authentication. The keys are stored in the database and if an API call
is made without a key or a bad key, the call is denied and an error
message is returned.

Key-based authentication
~~~~~~~~~~~~~~~~~~~~~~~~

As an example, let's write a function that returns the number of users
that have viewed the site in the last x minutes.

.. code:: php

    function count_active_users($minutes=10) {
        $seconds = 60 * $minutes;
        $count = count(find_active_users($seconds, 9999));
        return $count;
    }

Now, let's expose it and make the number of minutes an optional
parameter:

.. code:: php

    elgg_ws_expose_function("users.active", 
                    "count_active_users", 
                     array("minutes" => array('type' => 'int',
                                              'required' => false)),
                     'Number of users who have used the site in the past x minutes',
                     'GET',
                     true,
                     false
                    );

This function is now available and if you check ``system.api.list``, you
will see that it requires API authentication. If you hit the method with
a web browser, it will return an error message about failing the API
authentication. To test this method, you need an API key. Fortunately,
there is a plugin called apiadmin that creates keys for you. It is
available in the Elgg plugin repository. It will return a public and
private key and you will use the public key for this kind of API
authentication. Grab a key and then do a GET request with your browser
on this API method passing in the key string as the parameter
``api_key``. It might look something like this:
http://yoursite.com/services/api/rest/xml/?method=users.active&api_key=1140321cb56c71710c38feefdf72bc462938f59f.

Signature-based authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :doc:`web-services/hmac` is similar to what is used with OAuth or
Amazon's S3 service. This involves both the public and private key. If
you want to be very sure that the API calls are coming from the
developer you think they are coming from and you want to make sure the
data is not being tampered with during transmission, you would use this
authentication method. Be aware that it is much more involved and could
turn off developers when there are other sites out there with key-based
authentication.

OAuth
~~~~~

With the addition of the OAuth plugin, Elgg also fully supports the
OAuth 1.0a authorization standard. Clients can then use standard OAuth
libraries to make any API calls to the site.

User authentication
-------------------

So far you have been allowing developers to pull data out of your Elgg
site. Now we'll move on to pushing data into Elgg. In this case, it is
going to be done by a user. Maybe you have created a desktop application
that allows your Users to post to the wire without going to the site.
You need to expose a method for posting to the wire and you need to make
sure that a user cannot post using someone else's account. Elgg provides
a token-based approach for user authentication. It allows a user to
submit their username and password in exchange for a token using the
method ``auth.gettoken``. This token can then be used for some amount of
time to authenticate all calls to the API before it expires by passing
it as the parameter ``auth_token``. If you do not want to have your
users trusting their passwords to 3rd-party applications, you can also
extend the current capability to use an approach like OAuth.

Let's write our wire posting function:

.. code:: php

    function my_post_to_wire($text) {
        
        $text = substr($text, 0, 140);

        $access = ACCESS_PUBLIC;
       
        // returns guid of wire post
        return thewire_save_post($text, $access, "api");        
    }

Exposing this function is the same as the previous except we require
user authentication and we're going to make this use POST rather than
GET HTTP requests.

.. code:: php

    elgg_ws_expose_function("thewire.post", 
                    "my_post_to_wire", 
                     array("text" => array('type' => 'string')),
                     'Post to the wire. 140 characters or less',
                     'POST',
                     true,
                     true
                    );

Please note that you will not be able to test this using a web browser
as you did with the other methods. You need to write some client code to
do this. There is some example client code in ``/engine/lib/api.php``.
Take a look at `send\_api\_post\_call()`_. You can also do a search for
clients that have been written for the APIs of Flickr or Twitter or any
other similar API. You will find a wide variety written in almost any
language you can think of.

Building out your API
---------------------

As soon as you feel comfortable with Elgg's web services API framework,
you will want to step back and design your API. What sort of data are
you trying to expose? Who or what will be API users? How do you want
them to get access to authentication keys? How are you going to document
your API? Be sure to take a look at the APIs created by popular Web 2.0
sites for inspiration. If you are looking for 3rd party developers to
build applications using your API, you will probably want to provide one
or more language-specific clients.

.. _send\_api\_post\_call(): http://reference.elgg.org/lib_2api_8php.html#ee7382c2cbf1ad49ac6892556d3eaff2

Determining the authentication available
----------------------------------------

Elgg's web services API uses a type of `pluggable authentication module
(PAM)`_ architecture to manage how users and developers are
authenticated. This provides you the flexibility to add and remove
authentication modules. Do you want to not use the default user
authentication PAM but would prefer using OAuth? You can do this.

The first step is registering a callback function for the *rest, init*
plugin hook:

.. code:: php

    register_plugin_hook('rest', 'init', 'rest_plugin_setup_pams');

Then in the callback function, you register the PAMs that you want to
use:

.. code:: php

    function rest_plugin_setup_pams() {
        // user token can also be used for user authentication
        register_pam_handler('pam_auth_usertoken');

        // simple API key check 
        register_pam_handler('api_auth_key', "sufficient", "api");
            
        // override the default pams
        return true;    
    }

When testing, you may find it useful to register the
``pam_auth_session`` PAM so that you can easily test your methods from
the browser. Be careful not to use this PAM on a production site because
it could open up your users to a `CSRF attack`_.

Right now, the only other PAMs publicly available besides those provided
by the Elgg core are the OAuth PAMs. See `Justin Richer's OAuth plugin`_
for more detail.

.. _pluggable authentication module (PAM): http://en.wikipedia.org/wiki/Pluggable_Authentication_Modules
.. _CSRF attack: http://en.wikipedia.org/wiki/Csrf
.. _Justin Richer's OAuth plugin: http://community.elgg.org/pg/plugins/jricher/read/385119/oauth

Related
-------

.. toctree::
   :maxdepth: 1
   
   web-services/hmac