Strict Standards: Declaration of action_plugin_captcha::register() should be compatible with DokuWiki_Action_Plugin::register($controller) in /home/shared/community.kohovolit.eu/www/lib/plugins/captcha/action.php on line 15

Warning: Cannot modify header information - headers already sent by (output started at /home/shared/community.kohovolit.eu/www/lib/plugins/captcha/action.php:15) in /home/shared/community.kohovolit.eu/www/inc/auth.php on line 339

Warning: Cannot modify header information - headers already sent by (output started at /home/shared/community.kohovolit.eu/www/lib/plugins/captcha/action.php:15) in /home/shared/community.kohovolit.eu/www/inc/actions.php on line 162
api [KohoVolit.eu API (beta)]
 

Strict Standards: Declaration of Doku_Renderer_metadata::table_open() should be compatible with Doku_Renderer::table_open($maxcols = NULL, $numrows = NULL, $pos = NULL) in /home/shared/community.kohovolit.eu/www/inc/parser/metadata.php on line 24

Strict Standards: Declaration of Doku_Renderer_metadata::table_close() should be compatible with Doku_Renderer::table_close($pos = NULL) in /home/shared/community.kohovolit.eu/www/inc/parser/metadata.php on line 24

KohoVolit.eu API (beta)

KohoVolit.eu API provides access to all KohoVolit.eu data. It allows to use our data by anyone either for analyses or to build other websites and applications. Actually, the KohoVolit.eu applications (eg. NapišteJim.cz and NapíšteIm.sk) are written on top of that API as well.

You execute API calls as HTTP requests to http://api.kohovolit.eu, either from a server-side script (eg. PHP, Python, Ruby, etc.) or a client-side script (eg. Javascript). Requested data are returned as a body of the corresponding HTTP response.

The API is designed to conform to REST principles, hence referred as RESTful. Instead of calling API functions you access API resources that provides various kinds of data (eg. political parties, MPs (members of parliament), voting records, constituencies, etc.). Each resource is accessible through a unique URL in the form http://api.kohovolit.eu/project-name/resource-name, eg. http://api.kohovolit.eu/wtt/MessageToMp. Read-only access is allowed to the data through API from remote. It is implemented by the GET method of the HTTP protocol.

A short informal introduction to the RESTful API concept is explained in the first section of this article.

List of resources (functions)

Using KohoVolit.eu API

The API can be used by two ways. First, directly by HTTP requests from a script or a web browser window. Second, using a client library ApiClient that simplifies calling of API requests in a script. That client library is different for each scripting language.

A third way exists when using API from a PHP script on the same host. Since the API itself is implemented in PHP, API calls from localhost can be served by including source code of a resource and executing it. This is much more efficient than HTTP communication. There is another client library ApiDirect with the same interface as ApiClient but implementing API calls this way instead of sending HTTP requests. Besides, it is the only way for a write access to data through API.

All texts in KohoVolit.eu data use UTF-8 encoding. Therefore any accented characters in URLs or in parameters (when using the client library) must be UTF-8 encoded.

Resource names and project names are case-sensitive.

Some of the resources may be private – not accessible from remote.

Using API directly by HTTP requests

A basic usage pattern is to make an HTTP request to an URL in the form http://api.kohovolit.eu/project-name/resource-name?parameters from a script or a web browser window. For example try to type

http://api.kohovolit.eu/data/Mp?last_name=Svoboda&first_name=Pavel

into the address bar of your web browser. You get all MPs satisfying the specified first name and last name who are shown in a text format.

You can specify any number of pairs parameter-name=parameter-value separated by & character within parameters. Only the results satisfying all given constraints are returned. It is like a filter or like a WHERE condition in SQL query with all expressions joined by AND operator.

Available resources in each project as well as parameters that can be used for a particular resource are listed in the section on APIs of the KohoVolit.eu projects.

Error handling of API calls exploits HTTP status codes. Standard “200 OK” status code is indicated and a result is returned in the body of the HTTP response in case of a successful request. Otherwise, the status code indicates which error occured and its description can be found in the body. Examples of such status codes are “404 Not Found” when requesting non-existing resource, “503 Service Unavailable” when API is temporary unavailable, etc.

Data can be requested in a particular format. Just append the desired format to the resource name, eg.

http://api.kohovolit.eu/data/Mp.xml?last_name=Svoboda&first_name=Pavel

Available formats are XML, JSON, PHP (returns PHP-serialized value) and CSV. The CSV format is suitable only for two-dimensional data. If no format is specified, the data are returned as a plain text.

Note. Unknown (or undefined) string values are distinguished from values known to be empty in the database. The former is represented by NULL while the latter by an empty string. Use sequence \N to specify NULL within the parameters. For example, to get all MPs with no middle name and unknown birthdate use

http://api.kohovolit.eu/data/Mp?middle_name=&born_on=\N

Using API by a client library

A more convenient way to use the API from a script than making HTTP requests yourself is to download and use a client library ApiClient. The simple library (actually consisting of one simple class) wraps all the stuff to make a HTTP request and process a received response for a particular scripting language. Currently, there is only a version for PHP. Writing the client library for other languages is welcomed.

First, download the ApiClient library for PHP and include it from your script. Then you instantiate the class to make an API client that holds some common properties of all following API calls. Any number of API calls can be executed through that client by calling its read method. Example:

<?php
require 'ApiClient.php';
$api = new ApiClient('data', 'json');
$mps1 = $api->read('Mp', array('last_name' => 'Svoboda', 'first_name' => 'Pavel'));
echo $mps1;
$mps2 = $api->read('Mp', array('middle_name' => '', 'born_on' => null));
...

Parameters of the ApiClient class constructor are name of the project to access resources from and a desired format of the data. If you need to access resources of another project or to get results in a different format, you need to create another API client.

Parameters of the read method are a resource name and an associative array of parameters and their values to constrain the entities to read.

If an API call fails, an exception is thrown. So, the call should be enclosed in a try-catch block.

When creating an API client instance, you can specify an array with default parameters as an optional third parameter. Those parameters will be automatically appended to parameters of each API call made through that client. You can still override the value of any default parameter by including it with another value among parameters of a particular API call.

<?php
require 'ApiClient.php';
$api = new ApiClient('data', 'php', array('parliament_code' => 'cz/psp'));
try {
    $constituencies = $api->read('Constituency', array('since' => '2002-06-15'));
    print_r(unserialize($constituencies));
    $c12 = unserialize($api->readOne('Constituency', array('id' => 12)));
    echo $c12['name'];
} catch (Exception $e) {
    echo 'ERROR: ' . $e->getMessage();
}

This example demonstrates working with PHP-serialized data format, exception handling and default parameters. Only the constituencies of parliament with code cz/psp are considered in both API calls.

Additionally, the example introduces a readOne method. It is usefull when you know, that result of the API call will be only one entity. Instead of returning one-element array of entities (that are associative arrays themselves) that would return the read method, readOne returns directly that entity. You can then write clearer $c12['name'] instead of $c12[0]['name']. If you use readOne and multiple entities satisfy the given parameters a random one is returned.

Using API from PHP on localhost

In case of using API from a PHP script running on the same machine as the API is installed on, functions serving API resources can be included and executed directly eliminating overhead of the HTTP communication. Another client library ApiDirect serves for that purpose. Its interface is very similar to the one in ApiClient.

Download the ApiDirect library and include it from your script. Usage is almost the same as with ApiClient, try:

<?php
const API_DIR = '/home/shared/api.kohovolit.eu';
require 'ApiDirect.php';
$api = new ApiDirect('data');
$mps = $api->read('Mp', array('last_name' => 'Svoboda', 'first_name' => 'Pavel'));
print_r($mps);

First, you must define an API_DIR constant specifying where on the filesystem is the API installed. Format of the data is not specified in instantiation of the client, the data are always returned as a PHP value. Type of that value is completely up to the particular resource, but most often it will be an array. Default parameters can be set as an optional second parameter of the ApiDirect constructor.

ApiDirect is the only way to modify data through API. There is no way to manipulate data from remote.

Creating, updating and deleting data is achieved by other methods of ApiDirect class. All CRUD methods are:

  • read(resource-name, params), readOne(resource-name, params)
  • create(resource-name, data)
  • update(resource-name, params, data)
  • delete(resource-name, params)

Argument params stands for an array of constraints or a filter that data to read, update or delete must satisfy. Argument data contains data for created or updated entities. Most often it is an associative array of field names and their values to set for the created entity or for all updated entities. In create method the argument data can be an array of associative arrays specifying multiple entities to create.

Not all resources implement all those methods. Typically, resources that are front-ends to database tables implement all CRUD operations, while resources that provide views to the data, aggregates or searches implement only the read methods. When a non-existing method is called, an exception “405 Method Not Allowed” is thrown.

Return value of the create, update and delete methods is an array of associative arrays with primary key values that identifies all created, updated or deleted entities. Database generated id-s (or other surrogate keys) of created entities can be found in that array. In case that a simple associative array is given to the create method (thus specifying only one entity), the return value is one associative array with primary key values instead of an one-element array of associative arrays.

Example of manipulating data through ApiDirect:

<?php
const API_DIR = '/home/shared/api.kohovolit.eu';
require 'ApiDirect.php';
$api = new ApiDirect('data');
$created = $api->create('Constituency', array(
    array('name' => 'Náchod (47)', 'short_name' => '47', 'parliament_code' => 'cz/senat'),
    array('name' => 'Rychnov nad Kněžnou (48)', 'short_name' => '48', 'parliament_code' => 'cz/senat')));
$rid = $created[1]['id'];
$api->update('Constituency', array('id' => $rid), array('description' => '...some description...'));
$deleted = $api->delete('Constituency', array('short_name' => '47'));
print_r($deleted);

Resources of KohoVolit.eu projects

API resources of KohoVolit.eu projects are described in detail in the API reference.

Installing and extending KohoVolit.eu API

Installation of KohoVolit.eu API is needed to install and run KohoVolit.eu applications on your own server. You don't need to install the API to access KohoVolit.eu data from http://api.kohovolit.eu.

The installation means to download its PHP source codes, to modify some configuration files and to add a new section for the domain where the API will be hosted to your Apache configuration file.

Alter the main configuration file config/settings.php of the API and possibly also configuration files of individual projects' APIs in projects/*/config/settings.php.

Alter database connection files in config/db/ for an admin (full access) and for a user (read-only access).

Alter Apache configuration directives in the file config/apache.conf to correspond with the domain where your API installation will be hosted and with filesystem location of the API files. Then copy content of that file into your existing Apache configuration file and restart Apache.

The API should work now.

Adding a new API resource

The only thing that is needed to add a new API resource MyResource to a project some-project is to create a file MyResource.php in directory projects/some-project/resources that implements a class MyResource.

The class must implement some of the following methods:

  • read($params)
  • create($data)
  • update($params, $data)
  • delete($params)

Meaning of the methods' arguments is described in section Using API from PHP on localhost. Those methods must be declared as public static.

There are no requirements on the value returned by the methods. The value will be simply passed a result of the API call. However, by convention the methods create, update and delete return primary key values that allow to identify which entities were created, updated or deleted.

Throw an exception with appropriate HTTP status code and a more specific description to indicate error in processing, eg.

throw new Exception("The API resource <em>Scraper</em> is not implemented for parliament <em>$parliament</em>.", 400);

You can use the following constants defined in the main configuration file of the API:

Name Meaning Default value
API_DOMAIN domain the API is hosted on http://api.kohovolit.eu
API_ROOT filesystem path to API installation /home/shared/api.kohovolit.eu
API_LOGS_DIR path where log files are beeing saved API_ROOT/logs
API_FILES_DIR path where binary files related to data in the database (eg. images) are stored API_ROOT/www/files

Database queries are performed using the FIXMEQuery class.

Keep in mind that the read method is publicly accessible, while the other three can be called only from localhost through ApiDirect.

The best way to start is to clone an existing resource and alter it.

Adding a new project API

To make a new project my-project to be accessible through API create a directory projects/my-project.

Create resources of the project into its resources subdirectory following the previous section.

If there are some configuration settings that differs in each installation of the API (eg. filesystem paths, URLs, database credentials, error reporting level, etc.) make a config subdirectory and type them into file config/settings.php.

If some universal code should be executed before serving of each resource, type the code into a setup.php file in the project directory. It is the right place for an undefined classes autoloader for an example.

If there are some auxiliar classes that does not represent resources, move them to a classes subdirectory.

Thus the complete directory structure of the new project my-project is:

projects/
    my-project/
        classes/
        config/
        resources/
        setup.php

If config/settings.php or setup.php are present for the project, they are included in the respective order before executing code of any resource of this project.

Directory structure of the API source codes

classes/                    classes that implements the API system
config/                     configuration files of the API system
    db/                     database connection files
        settings.php        main configuration file
data model/                 data model description and database scripts
doc/                        configuration files for generated documentation
logs/                       log files of API processes (eg. of data updating)
projects/                   projects accessible through API
    data/                   common database
        classes/            auxiliar classes of the project
        config/             configuration files of the project
            settings.php    project configuration file
        resources/          resources of the project
        setup.php           a start-up code of all project resources
    wtt/                    WriteToThem project
    ...                     other projects
www/                        webserver document root
    doc/                    generated documentation to the API system
    files/                  binary files related to data in the database (eg. images)
    index.php               universal controler - entry point to the API
README                      a read-me file
setup.php                   a start-up code of the API system

Control flow of an API request

When an API resource is requested by its unique URL, rewriting rules in the Apache configuration file redirect it to an universal controller index.php and pass the resource name and the project name as a parameter. Eg.

http://api.kohovolit.eu/data/Mp?last_name=Svoboda&first_name=Pavel

is redirected to

http://api.kohovolit.eu/www/index.php?project=data&resource=Mp&last_name=Svoboda&first_name=Pavel

The index.php includes the API settings and setup file and calls ApiServer methods to process the HTTP request and send a response.

Project specific settings and setup files are included in processing of the request by ApiServer, if they exist. Then the resource class source file is included and its appropriate method is executed. Finally the result is encoded into the desired format and returned as a HTTP response.

 
api.txt · Last modified: 27.06.2013 12:36 by giro
 
Except where otherwise noted, content on this wiki is licensed under the following license:CC Attribution 3.0 Unported
Recent changes RSS feed