Omeka REST API, Spring’s RestTemplate and Jackson JSON library (part 1)

I had considered building my own collections management system. This would have had some advantages, but several disadvantages. The main disadvantage would have been time. Another would be the need to know the standards inside out – e.g. properly implementing / adhering to Dublin Core metadata standards.

It wasn’t difficult to find a collections management system that would provide the basis for my own collections (and those of any partner museums / galleries along the way). Omeka has some definite advantages: it is open source, so I can see why things happen the way they do and modify if necessary; it is extensible with plugin development “hooks”; it has some similarities in its philosophy with WordPress, the world’s most installed content management and blogging system; it is moving to the Zend framework – not my framework of choice, but one that is widely used and thus provides access to simplified APIs; it has a decent community of support around it.

I initially tried setting everything up myself with Omeka – I created a VirtualBox Ubuntu virtual server and eventually got it working, though there was a lot of flapping around with Apache and modrewrite. Later, though, I discovered a Turnkey Linux Omeka install. While it is possible to install the operating system (Debian Linux), apache, PHP, MySQL, and Omeka, from a downloaded ISO image (once burned to CD or mounted directly while starting a virtual server), the easiest approached is to download the VMDK disk image and use that when creating a Linux virtual server with VirtualBox or VMWare. These Turnkey Linux images tend to be cut down to almost the bare minimum. The Omeka one is a headless server – that is, there is no desktop with mouse and pointer. It only takes up 238 MB of space and can run with a fairly small memory footprint – easily under 512MB. Whether or not I would use one of the Turnkey Linux images for a production server, I am not sure – might need more optimisation – but for development purposes it is perfect. I can have many instances of Omeka installed and run the ones I want.

The Turnkey Linux Omeka image was only at version 2.0.1, but was easily upgraded to the latest version (2.1.4).


Spring for Android provides support for, amongst other things, Spring’s RestTemplate class. This allows an Android app to connect to a REST API and retrieve resource data in some representation or other. In the case of Omeka, from version 2.1 there is support for REST with JSON documents returned. The REST API is turned off by default and must be explicitly turned on in Omeka’s admin control panel. In addition, only items and collections marked as public will be returned to a REST API request.

The following is an example of a JSON document returned from a request to http://192.168.1.17/api/items/1 (running in a VirtualBox virtual server on my Linux PC):

{"id":1,"url":"http://192.168.1.17/api/items/1","public":true,"featured":false,"added":"2014-05-12T20:14:59+00:00","modified":"2014-05-12T20:20:43+00:00","item_type":null,"collection":null,"owner":{"id":1,"url":"http://192.168.1.17/api/users/1","resource":"users"},"files":{"count":0,"url":"http://192.168.1.17/api/files?item=1","resource":"files"},"tags":[],"element_texts":[{"html":false,"text":"Test Title","element_set":{"id":1,"url":"http://192.168.1.17/api/element_sets/1","name":"Dublin Core","resource":"element_sets"},"element":{"id":50,"url":"http://192.168.1.17/api/elements/50","name":"Title","resource":"elements"}},{"html":false,"text":"Test Description","element_set":{"id":1,"url":"http://192.168.1.17/api/element_sets/1","name":"Dublin Core","resource":"element_sets"},"element":{"id":41,"url":"http://192.168.1.17/api/elements/41","name":"Description","resource":"elements"}}],"extended_resources":[]}

Not particularly easy to read, is it? The only data of real interest to my consuming Android app for this particular item is the id number (1), the title (“Test Title”) and the description (“Test Description”). Pretty much everything else can be ignored. Part of the reason it is difficult to read is because each item (our cultural objects are just known as items) is made up of elements. Each field value, such as title, description, creator, and so on, are stored as separate rows in the element_texts table.

It’s a little clearer when the JSON is formatted with proper indentation (e.g. using one of many free sites like http://www.freeformatter.com/json-formatter.html):

{
   "id": 1,
   "url": "http://192.168.1.17/api/items/1",
   "public": true,
   "featured": false,
   "added": "2014-05-12T20:14:59+00:00",
   "modified": "2014-05-12T20:20:43+00:00",
   "item_type": null,
   "collection": null,
   "owner": {
      "id": 1,
      "url": "http://192.168.1.17/api/users/1",
      "resource": "users"
   },
   "files": {
      "count": 0,
      "url": "http://192.168.1.17/api/files?item=1",
      "resource": "files"
   },
   "tags": [],
   "element_texts": [
      {
         "html": false,
         "text": "Test Title",
         "element_set": {
            "id": 1,
            "url": "http://192.168.1.17/api/element_sets/1",
            "name": "Dublin Core",
            "resource": "element_sets"
         },
         "element": {
            "id": 50,
            "url": "http://192.168.1.17/api/elements/50",
            "name": "Title",
            "resource": "elements"
         }
      },
      {
         "html": false,
         "text": "Test Description",
         "element_set": {
            "id": 1,
            "url": "http://192.168.1.17/api/element_sets/1",
            "name": "Dublin Core",
            "resource": "element_sets"
         },
         "element": {
            "id": 41,
            "url": "http://192.168.1.17/api/elements/41",
            "name": "Description",
            "resource": "elements"
         }
      }
   ],
   "extended_resources": []
}

We can see more easily that the owner is the Omeka user with id 1, that there are no connected files (count is 0) and that there are no tags (annotations). There is a sub-document of element_texts which causes some complication. It would be nice if we could drill-down into each element text and immediately see that one is a title, another a description, and so on. What we get, though, is the value first and the element name within a further sub-document (the element). This isn’t insurmountable, but probably means that using automagic to automatically populate Java classes is out of the question (e.g. using RestTemplate’s getForObject… restTemplate.getForObject(url, Item.class);) – though I haven’t ruled this approach out just yet.


So where am I now? I can get the Android app to connect to the Omeka site and retrieve a JSON document for the RESTFul url supplied. However, I have yet to map the retrieved document to my internal Java Item class. Hopefully in part 2 I can get a bit closer to that goal.

0 replies

Leave a Reply

Want to join the discussion?
Feel free to contribute!

Leave a Reply

Your email address will not be published. Required fields are marked *