FSI Server OpenAPI – Part II: Getting started writing a client application

As described in part I of this series the FSI Server Open API consists of two parts: The part to manage images on the server requires the client application to log in before changing any data on the server. This part can be used in a REST-like style, although strictly speaking it is not REST, as it uses Cookies for session authentication.

In general, no matter what programming language you are using, any HTTP Client library can be used to communicate with FSI Server. Using a REST framework is recommended though, as it simplifies client side applications. The Java examples in this blog series will use the client API that is part of Jersey, the reference implementation of JAX-RS. To run the examples the following five jar files are required: jersey-client, jersery-core, jsr311-api, jersey-apache-client and the apache-httpclient. We also provide a few useful classes to help you getting started, so please download the FSI Server Development Pack from the download area and place the included jar in your libs directory.

To demonstrate how easy a client for the FSI Server can be developed, the PHP examples used in this and the following articles will not make use of a special framework, but instead will use the PHP curl library to handle the HTTP communication.

Before we start with the first examples here are a few words about how the URLs used in the API are put together: All requests to manage data on the server need to be directed to a URL beginning with http://your.fsi-server.com/fsi/service/… followed by the service type. Currently available service types are

login – to handle everything related to logging in,
logout – to handle logout requests,
image – to handle image management requests,
directory – to handle directory management requests,
prefs – for requesting the users preferences,
status – for requesting the servers status,
sessionrefresh – allowing to prevent the session from expiring.

Logging in requires three steps: requesting a salt from the imaging server, generating a hash value using the password and the salt, sending the hashvalue and the username to the server. This first Java example will initialize the HTTP client and perform the login.

ApacheHttpClientConfig clientconfig = new DefaultApacheHttpClientConfig();
clientconfig.getProperties().put(ApacheHttpClientConfig.PROPERTY_HANDLE_COOKIES, true);
Client client = ApacheHttpClient.create(clientconfig);
String serviceURL = "http://your.fsi-server.com/fsi/service/";

The resulting client object can be used throughout the complete session to send all required requests. Next, we’ll send a GET request to the login-URL and extract the salt from the response and use it to generate the login hash.

>WebResource r = client.resource(serviceURL + "login");
String s = r.get(String.class);
SaltResponse sr = JAXB.unmarshal(new ByteArrayInputStream(s.getBytes()), SaltResponse.class);
String salt = sr.salt;
String passwordhash = sha256(password);
String loginhash = sha256(salt+passwordhash);

Finally, the login hash needs to be posted to the login service URL together with the username:

Form form = new Form();
form.add("username", username);
form.add("password", loginhash);
LoginResponse loginResponse = resource.post(LoginResponse.class, form);

The LoginResponse object contains an instance variable describing if the login was successful. In case the login was not successful, then the reason will also be noted in the result object. All follow-up requests sent to WebResources create by the client instance will contain the session and will therefore be treated as authenticated.

Once it has finished its work, your client application should log out:

WebResource logoutResource = client.resource(serviceURL + "logout");

So much for example Java code. Here’s the PHP code that performs more or less the same sequence of operations as the Java code above.

Start by initializing the curl library:

$curlhandle = curl_init();
curl_setopt($curlhandle, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curlhandle, CURLOPT_HEADER, 0);
curl_setopt($curlhandle, CURLOPT_COOKIEFILE, "/tmp/cookies.txt");
curl_setopt($curlhandle, CURLOPT_COOKIESESSION, TRUE);

Request the salt and calculate the password hash.

curl_setopt($curlhandle, CURLOPT_URL, $serviceURL."login");
$saltresponse = curl_exec($curlhandle);
$salt = parseSaltResponse($saltresponse)
$passwordhash = hash("sha256",$password);
$loginhash = hash("sha256",$salt.$passwordhash);

Post the login data to authenticate the session.

$postdata = "username=".$username."&password=".$loginhash;
curl_setopt($curlhandle, CURLOPT_POST, TRUE);
curl_setopt($curlhandle, CURLOPT_POSTFIELDS, $postdata);

After the work is done the PHP client should also not forget to log out.

curl_setopt($curlhandle, CURLOPT_HTTPGET, TRUE);
curl_setopt($curlhandle, CURLOPT_URL, $serviceURL."logout");

The next blog entry in this series will show you how your client application can upload images to FSI Server.