Programming the KwaMoja API - An introduction

 Introduction

This is a series of blog posts that will attempt to teach the programming and debugging of client applications for KwaMoja, using the API that comes bundled with it.

This can seem daunting at first, but as I hope to show you when you look behind the magic, it is really very easy for anyone who knows a programming language.

KwaMoja comes with a simple to use and flexible API that allows client programs to access KwaMoja in a safe and secure manner. If you wish to write an application that accesses KwaMoja, either to post transactions, or to extract information, then you should use the API, rather than try to access the KwaMoja database directly, as the API makes sure that the integrity of the data is maintained.

In this series I intend to show how to create a simple PHP client application, how to debug that application, then I hope to move on to writing a client in a different programming language, and finally how to extend the API.

The Protocol

The API uses the XML-RPC protocol to communicate between the client and the server. This was chosen because it is lightweight, simple, and easy to use. The API uses the XML-RPC for PHP external library, rather than the XML-RPC extension for PHP as it is small lightweight, and the extension is often not installed by default, so would add another dependency to KwaMoja. 

However the API was structured in a manner that allows other protocols to be used very easily. All that would need to be done to use the SOAP protocol for instance would be to create an api_soap.php file with the same functions as the api_xmlrpc.php file.

Setting up the server:

Before we start on the client there is one thing needed to be changed on the server side. This is to set the database to be used inside the api/api_php.php file. Mine is simply called kwamoja, so line 6 of api_php.php should read as:

$api_DatabaseName='kwamoja';

That is it for this introductory blog. Next time we will get down to some serious programming by starting work on our client application.