About

The Web API Bridge is an HTTP service that automatically translates HTTP-based Web API requests into calls to MySQL SQL Stored Procedures, and then returns JSON-encoded output. The Web API Bridge is currently implemented in PHP and is expected to run atop of Apache 2.

Apart from indicating where the software has been installed, the Web API Bridge has no local configuration - the domain of the URL requested is used to perform a text entry DNS-lookup that returns the database name and IP addresses associated with the target MySQL server. If no record is found, the database is assumed to be available on the localhost, and the database name is determined from the domain name. The target MySQL server must be configured to allow access to the Web API Bridge. When a remote MySQL server is used the connection is secured using x509 certificates.

The rest of this page provides a primer on some important aspects of the Web API Bridge. The Download section below provides quick access to the PHP source code of the Web API Bridge. The Quick Start section below describes how to download and install the Web API Bridge on a Linux server that contains Apache 2 - a more indepth discussion of setup is provided on the VM Setup page. The Configuration section describes how to configure DNS text entries that supply the required information to the Web API Bridge. The Database Requirements section provides an SQL Stored Procedure that must be installed into any specific database that will be accessed by the Web API Bridge. The Database Security section describes how to grant the Web API Bridge access to a MySQL database. The Open Source section describes the license that the Web API Bridge is distributed under.

Download

The Web API Bridge may be downloaded using the link below:
Download the Web API Bridge

Quick Start

First decide where you want to install the Web API Bridge. As it is designed to run on Apache, the following instructions asume you will want to install it under '/var/www/'. To this end, the instructions below set an environment variable 'DOCUMENT_ROOT', which is then used to alter the Web API Bridge configuration file, and the Apache configuration file.

DOCUMENT_ROOT=/var/www/WEB_API_BRIDGE

Once downloaded, check that the MD5 sum of the package matches the following value:

sudo mkdir $DOCUMENT_ROOT
cd $DOCUMENT_ROOT
sudo wget http://www.webapibridge.org/client/webapibridge/resources/downloads/WebAPIBridge-1.0.5.tar.bz2
md5sum WebAPIBridge-1.0.5.tar.bz2

The 'md5sum' command will return the checksum and the name of the file:

767235ff974a924e1ef7b8bd0bd9030c WebAPIBridge-1.0.5.tar.bz2

Next unpack the archive, and configure the Web API Bridge.

sudo tar jxvf WebAPIBridge-1.0.5.tar.bz2 --no-same-owner
cd WebAPIBridge/1.0.5/webapibridge/configuration
sudo cp configuration.template.php configuration.php
sudo sed -i "s|%DOCUMENT_ROOT%|$DOCUMENT_ROOT|g" configuration.php
sudo cp apache2/WEB_API_BRIDGE.conf /etc/apache2/sites-available/WEB_API_BRIDGE.conf
sudo sed -i "s|%DOCUMENT_ROOT%|$DOCUMENT_ROOT|g" /etc/apache2/sites-available/WEB_API_BRIDGE.conf
sudo ln -sf ../sites-available/WEB_API_BRIDGE.conf /etc/apache2/sites-enabled/WEB_API_BRIDGE.conf

Finally, you need to setup a symbolic link that controls the active version of the software, as well as a link - using that link - to the index.php file.

cd $DOCUMENT_ROOT/WebAPIBridge
sudo ln -sf 1.0.5 latest
cd $DOCUMENT_ROOT
sudo ln -sf WebAPIBridge/latest/webapibridge/bin/index.php .

Now restart Apache2.

sudo service apache2 restart

DNS Configuration

For an HTTP request of the form 'http://api.myservice.com:8080', by convention, it is assumed that DNS information correponding to the database can be found by prefixing "db-" to the domain, e.g: 'db-api.myservice.com'. If the requested domain ends in '.local', due to being a local development domain, 'local-db-' is instead prefixed to the domain, and the '.local' suffix is replaced with '.org', e.g: 'local-db-api.myservice.org'. This is required so that public DNS can be used to return DNS information associated with a local domain.

The format of the txt record should be as follows where each IP address could be a different MySQL server:

<database name>@<ip address 1>, ...

Alternatively, domain names may be specified.

<database name>@<doman name>, ...

For example:

baseschema@db.baseschema.org

Note: the Web API Bridge will use the database that is prefixed with the database name and has the highest version number. Therefore, if there were sevaral baseschema databases, e.g., 'baseschema001', 'baseschema002', and 'baseschema003'; the last would be used.

Database Requirements

The Web API Bridge relies on the ability to call the SQL Stored Function below, which allows the Web API Bridge to retrieve the signature of each SQL Stored Procedure. This allows the Web API Bridge to map HTTP search parameters to SQL Stored Procedure parameters. The following may be cut and pasted into a MySQL interactive session, or may be added to your SQL schema definitions. Note: while the function below needs to be added to each inidividual database, the database name is also passed as a parameter because the function accesses the mysql.proc table, which is shared between databases.

DROP   FUNCTION Retrieve_Parameters_For;
DELIMITER //
CREATE FUNCTION Retrieve_Parameters_For
(
  $database                   CHAR(64),
  $name                       CHAR(99)
)
RETURNS blob
READS SQL DATA
BEGIN

DECLARE $ret BLOB;

SELECT param_list INTO $ret
FROM mysql.proc
WHERE db=$database
      AND name=$name
ORDER BY modified DESC LIMIT 1;

return $ret;

END
//
DELIMITER ;

In order for the Web API Bridge to execute this stored procedure, as well as any other stored procedures that are mapped from requested URLs, an account must be added to MySQL that is able to execute stored procedures.

The following command creates a 'public' account that is only allowed to execute stored procedures. As it is expected that a session id will be passed as a parameter for any stored procedures that require authorisation, this account is assumed to be publicly accessible.

mysql -u root -p
Enter password:
mysql> GRANT EXECUTE ON *.* TO 'public'@'localhost' IDENTIFIED BY 'public';

In practice, however, the host that is authorised to login as 'public' should be extremely secured.

HTTP Request to Stored Procedure Mapping

Requested URLs are mapped to SQL Stored Procedures using a fairly simple mapping. Any URL endpoints that beging with '/api/' are treated as API calls, and the rest of the endpoint is processed to generate a provisional procedure name by replacing any forward slash ('/') characters with underscores ('_').

The 'Retrieve_Parameters_For' stored function is used to determine what parameters should be passed, and in what order. An empty string is passed for any parameters that were not present in the URL search string.

For example,

/api/users/replace/?USER=45&given_name=Joe&family_name=Black

Might be processed to produce the following SQL Stored Procedure call, where the final two parameters were missing:

CALL users_replace( '45', 'Joe', 'Black', '', '' );

Note: The names of SQL Stored Procedures in MySQL are case-insensitive.

Open Source

An implementation of the Web API Bridge is distributed using the GPL v3 license.

If this license is inappropriate for your needs, please contact Cross Adaptive for alternative licensing options.