FSI Server OpenAPI – Part III: Uploading images.

As mentioned in the previous parts of this series of blog entries FSI Server provides a REST like API to manage data on the server. Part II showed how to log in and what the request URLs used in the API look like in general. The URLs for image operations have the following form:


This URI references the image available on the server at /path/to/image.jpg. This URI can be used to upload an image to this location or download the original image file from this location. Of course both operations require sufficient server side permissions.

Presuming your client application has successfully logged in as shown in the last episode of this blog series and also presuming that downloading images is allowed by the import profile the download can be triggered as would be expected by sending an HTTP GET request to the images URI. The response body will then contain the original image data.

Uploading is not more complicated but various ways of uploading are offered. The easiest way to upload an image is to send a PUT request to the images URI. The request body should contain the image data and the Content-Type header must specify the correct mime-type. The Java code for such an upload would look like this:

byte[] imagedata = readImageDataFromFile();
WebResource imageresource = c.resource(serviceURL + "image/" + targetPath);
Builder builder = imageresource.header("Content-Type", "image/jpg");
ActionResponse ar = builder.put(ActionResponse.class, imagedata);

The resulting ActionResponse object will contain fields indicating if the upload was successful or not.

Alternatively an image can be wrapped in an object prior to uploading. This allows storing a last-modified date in addition to just the raw image data. The code then looks as follows:

Image theImageObject = new Image();
ActionResponse ar = builder.put(ActionResponse.class, imagedata);

Specifying the content type in the latter example is not necessary as the Jersey client library will set the content-type header appropriately.
Using PHP the upload code would look similar to this:

curl_setopt($curlhandle, CURLOPT_PUT, TRUE);
$filehandle = fopen('test.jpg','r+');
curl_setopt($curlhandle, CURLOPT_INFILE, $filehandle);
curl_setopt($curlhandle, CURLOPT_HTTPHEADER, array("Content-Type: image/jpeg"));
curl_setopt($curlhandle, CURLOPT_INFILESIZE, filesize('test.jpg'));

In addition to uploading images using PUT requests, the OpenAPI als provides methods to upload images using POST requests. This is not very REST like, but allows developing clients using plattforms that do not support the whole HTTP commandset, e.g. Adobe Flash.

To upload images using POST, the requests must be directed at a different URL:


The request must be sent as multipart-formdata and should include at least the following body parts: “Lastmodified” containing the last-modified date of the image in Unix Timestamp format, “Filedata” containing the actual image data.

The API also offers a method of checking if a file can be uploaded prior to the actual upload. The main use case for this would be to check if the client application has the correct permissions to write to the specified directory and to check if there is enough disk space available. Checking this beforehand ensures that the possibly very large image file is only transferred if it can be processed.

This check request needs to be a POST request, directed at http://your.fsi-server.com/fsi/service/postupload. The Content-Type must be “application/x-www-form-urlencoded” and the body should include these parameters: “Dir” specifying the directory the image is supposed be saved in (“path/to” in the examples above), “Filename” containing the planned image filename (“image.jpg” in the previous examples), “Filesize” containing the size of the file in bytes and “Lastmodified” containing a Unix Timestamp. The response is either an XML or a JSON object containing a status code and if necessary an message explaining the reason why an image should not be uploaded as planned. More Details on the error codes can be found in the FSI Server OpenAPI manual available in the download area on http://www.fsi-viewer.com.

The next part of this blog series will describe how to handle directories on the FSI Server.