Replicant API

Introduction

Replicant API is an API server that hides automatic failover protection. User applications call Replicant API as they would a database service with SQL Stored Procedures. Replicant API acts as a routing mechanism that ensures that those procedure calls are directed to the current read-write node.

Calling a Replicant API instance

A Replicant API instance is called in a similar way to many other web services. The following example uses the PureJavascript 'Call' function, which abstracts an AJAX call. The handler that is passed takes a 'responseText' argument when called.

Call( "/call/", parameters, handler );
function ExampleCall()
{
	var parameters = GetSearchValues();
		parameters.command = "Users_Retrieve";
		
	Call( "/call/", parameters, ExampleCallHandler );
}

function ExampleCallHandler( responseText )
{
	var json = JSON.parse( responseText );
	
	if ( "OK" == json.status )
	{
		// Do something with returned JSON.
	}
}

How the call is handled

Resolving the database

When the call is received by Replicant API it uses the requested domain name to determine the database to access. The domain is stripped of top-level domains such as '.com', and the subdomain 'api.' to reveal the database prefix to use. For example, the database prefix of 'api.replicantdb.com' is 'replicantdb'. The database whose name contains the database prefix, and whose suffix is higheest numerical, is treated as the active database that the call is made against.

Marshalling the arguments

The arguments that are passed to the webserver as an encoding of an associative array, however, such a data structure does not have an order. Therefore, somehow the arguments passed to the webserver need to be mapped to the correct order of parameters that are passed to the SQL Stored Procedure. This is achieved by the Replicant API instance querying the definition of the stored procedure from the database, and parsing it to reveal the types of the parameters.

Calling the procedure

The SQL Stored Procedure is called by calling the ReplicantDB::CallProcedure function, which determines which database is read-write and performs the associated call.

Format of response

The response is returned to the caller as a JSON format that contains a results array, as well as other information values. The format is shown below:

{
	"error"     : "",
	"failover"  : "FALSE",
	"hostname"  : "pri-db (DB_HOSTNAME)",
	"message"   : "",
	"status"    : "OK",
	"warning"   : "",
	"URL"       : "/call/",
	"target_id" : "",
	"submit"    : "",
	"microsecs" : "550071",
	"results"   : [...]
}

'status' can either be "OK" or "ERROR". On error, a description is provided in 'error'. Any warnings are returned in 'warning'.