Improve My City API

You can refer to this page for a complete API reference of Improve-my-city

Following the latest trend of application interoperability, Improve-My-City introduced a complete functionality wrapping around its core features and elements in the form of RESTful services. Simple speaking, Improve-my-city has its own Application Programming Interface (API) to be used by 3rd party developers.

Technically speaking, REST isn’t specific to just APIs, it’s more of a generic concept, however, in our case talking about REST services is clearly in the context of an API. The basic needs of an API and how REST addresses them is explained below.

Requests

All APIs need to accept requests. Typically, with a RESTful API, a well-defined URL scheme is needed. Concerning that Improve-my-city is basically a Joomla extension and Joomla framework rules and guidelines should be strictly followed, the API requests are handle by a special controller called mobile.json So, in order to request, for example the list of issues, the controller “waits to receive” a request at this URL:

http(s)://<mydomain>/<myJoomla>/option=com_improvemycity&task=mobile.getIssues&format=json

To get the list of issue categories, the controller “waits to receive” a request at this URL:

http(s)://<mydomain>/<myJoomla>/option=com_improvemycity&task=mobile.getCategoriess&format=json

Responses

REST handles requests very easily, but it also makes generating responses easy. Similar to requests, there are two main components of a RESTful response: the response body, and a status code. The response body is pretty easy to deal with. All responses in REST on Improve-my-city are JSON, because it works well with JavaScript, and PHP has easy functionality for encoding and decoding it. If a consumer wishes to receive an different format (say XML response or open311 format), they’d just send an Accept header as a part of their request saying as much (”Accept: application/xml”). This is achieved with the format argument which at the moment accepts only JSON, thus format=json to be used. Future versions will support various formats though.

Moreover, next API version will handle in much more smarter (and more standardized) way the errors and other important status messages associated with requests, using HTTP status codes. This is one of great things about creating RESTful APIs. By using HTTP status codes, there is no need to come up with a error / success scheme on the API (although at this time simple error int/text codes are sent) , since it’s already done and provided by HTTP. For example, if a consumer POSTS to “getComments” and needs to report back a successful task completion, Improve-my-city will simply send a 201 status code (201 = Created). If it failed, it will send a 500 if it failed on consumer's end (500 = Internal Server Error), etc. This is just various HTTP headers to send back. Improve-my-city will be based on that:

Wikipedia: List of HTTP Status Codes.

What about security

First and foremost it is always suggested to use REST API on secure servers under SSL protection. That, of course, is not mandatory and API is still 100% usable. Nevertheless, Improve-my-city takes security measures to avoid packet sniffing up to a point by using password encryption/decryption techniques using a common secret key between server (Joomla site) and client (the API consumers).

As of version 2.5.2, Improve-my-city introduced the definition and setup of the API KEY. You can see a new menu on the administration site, where the administrator can set a unique 16 character long secret key as shown in the following screenshot (default key MUST always change):

The API KEY is now (2.5.2) stored on server's database instead on parameters (2.5.1) since Joomla component parameters are set on session which a hacker might somehow get access to it. This way, API KEY is never transmitted since models accessing it directly on the server side only.

Clients (API consumers) who wants to call the REST API must aware of this key. That means, its on administrator concern to whom will give access on server's data. At the moment, only the functions which put data in the server are tested against this key and not the ones which get data from server. This will change on future versions and probably different keys will be used for get/set tasks. This will help to log requests and maybe, for example, apply a billing policy based on the number of requests per day.

Also, special measures are taken for those who just want to use Improve-my-city only as Joomla component and wants to forbid all API calls. Version 2.5.2 brings new setting as shown in the following screenshot that switch-off completely the mobile.json controller (this is the default value when installing Imrove-my-city on your Joomla site)

##How to use the API KEY to encrypt your passwords

Most Improve-my-city API calls take these two arguments: username which is straight forward and encrypted_password.

Encrypted_password is the actual user password hashed with the API key in order to transmit GET/POST requests not with just plain text. This way, even if a hacker sniffs out the packet with a sniffer, he only get the hashed string on the actual password. It would be very difficult for him to decrypt the password without the API KEY. Below, an example of how to encrypt the password according to Improve-my-city REST API, is given in PHP:

The code is taken from http://www.androidsnippets.com/encrypt-decrypt-between-android-and-php and you can refer to it for Android (java) calls as well.

class MCrypt
{
		private $iv  = '1270923140017418'; 
		private $key = '1270923140017418'; 

		function __construct()
		{
		}

		function encrypt($str) {

		  $iv = $this->iv;

		  $td = mcrypt_module_open('rijndael-128', '', 'cbc', $iv);

		  mcrypt_generic_init($td, $this->key, $iv);
		  $encrypted = mcrypt_generic($td, $str);

		  mcrypt_generic_deinit($td);
		  mcrypt_module_close($td);

		  return bin2hex($encrypted);
		}

		function decrypt($code) {
		  //$key = $this->hex2bin($key);
		  $code = $this->hex2bin($code);
		  $iv = $this->iv;

		  $td = mcrypt_module_open('rijndael-128', '', 'cbc', $iv);

		  mcrypt_generic_init($td, $this->key, $iv);
		  $decrypted = mdecrypt_generic($td, $code);

		  mcrypt_generic_deinit($td);
		  mcrypt_module_close($td);

		  return utf8_encode(trim($decrypted));
		}

		protected function hex2bin($hexdata) {
		  $bindata = '';

		  for ($i = 0; $i < strlen($hexdata); $i += 2) {
				$bindata .= chr(hexdec(substr($hexdata, $i, 2)));
		  }

		  return $bindata;
		}

}

$username = 'bobsponge';
$password = 'patrick123';


$mcrypt = new MCrypt();
$encrypted_password = $mcrypt->encrypt($password);

Having encrypted_password you can pass it over to the API and take advantage of the complete functionality of Improve-my-city to your application either it's on PHP, Java, C++, Python and whatever language supports HTTP requests and JSON handling for the responses.