mod_okioki - RESTful data service, apache module
================================================

Okioki is a Maori word, meaning: to rest. 

There is a lot of infrastructure build for webservices, such as load balances,
caching/proxy servers, compression, encryption, authentication, auhtorization and logging.
By having this Okioki module between the application server and its database as a shim will
give you access to all this infrastructure. Okioki was designed to make it really easy
to make such a RESTful data service.

Design constraints for this module are:
- Correctness, i.e. everything is checked, don't allow sql injection.
- Performance, the primary reason to make this in C.
- Simple to use/configure.

Anatomy of a service
--------------------
A webservice is identified by the http method and url. In Okioki the url is defined
with an extended regular expression, with optional groups.

Each of the webservices has an SQL statement associated with it. Parameters used by the
SQL statement can be gotten from the http client in several ways.
- The first set of parameters are parsed from the url using its matching regular
  expression and groups.
- The second set is parsed from the query string.
- The third set from the cookies
- And the last set from the posted urlencoded form data.

The result of the SQL statement is written to the http client in a
CSV (comman seperated values). The result may also be written to a cookie (only the
value from the first row of the result).

It is recommended to create stored procedures for the more complicated services.


Example apache config
---------------------
Below is part of an apache configuration file. The first part loads
the module.

- Use of DBD commands to prepare the sql statements and use a resource pool
- Use of the Rewrite engine to convert RESTful URLs to simple urls.
- The OkiokiCommand has assigned to it:
 * a http method,
 * an url (under /tautoru),
 * That the result should be returned in CSV form,
 * the prepared statement to use,
 * and the parameters from a GET/POST form, to be used with the prepared statement

<IfModule !mod_okioki.c>
    LoadModule okioki_module modules/mod_okioki.so
</IfModule>

<VirtualHost *:80>
    DBDriver pgsql
    DBDParams "host=localhost dbname=tautoru user=tautoru password=xxxxxx"

    DBDPrepareSQL "select id, name from otp_algorithm;" sql_test
    DBDPrepareSQL "select name from otp_algorithm where id = %hhd;" sql_test_id

    #RewriteLog "/var/log/apache2/rewrite.log"
    #RewriteLogLevel 9

    RewriteEngine on
    RewriteRule ^/tautoru/test/(.*) /tautoru/test_id?id=$1

    <Location /tautoru>
        SetHandler okioki-handler
        OkiokiCommand GET /test CSV sql_test
        OkiokiCommand GET /test_id CSV sql_test_id id
    </Location>
</VirtualHost>