Extensive documentation

Although in theory a single starting URI should be enough to describe a REST API, we wanted to provide extensive documentation for all of our APIs. This not just helps us to keep track of our API features, it also helps developers to getting started with it.

The documentation lists all of the resources, possible representations and operations on these resources. For operations, sample entities as well as a list of possible response codes are listed. The documentation also provides URI template information and authentication requirements.

We developed our own template for creating REST documentations that transforms a XML-based descriptions of an API into a HTML file (or other formats such as plaintext or PDF). All example entities (in our case only JSON) have been validated and formatted, to assure correct and readable snippets.

URI as only ID

Another change was the introduction of URIs as the only way of identifying platform resources. While this is an obvious characteristic of REST, we were still referring to our internal resource IDs in some of our API calls in the previous version. Now we use URIs for everything.

Hyperlinks between resources

A side benefit of the URI-only approach is the increased linking between different resources. When a user creates a resource, it’s representation will not list his name or internal ID as the creator, but it will contain a hyperlink to the user’s URI. By providing useful links to the most important resources on the entry resource, a client can now navigate through the entire platform without having to know any URI pattern or template in advance.

Collection Resources

This is a bit controversial when it comes to URI design, but we decided to differentiate between a resource path prefix and a resource collection path prefix. So when the URI of a resource is /resource/{internal-id}, the corresponding collection resource is /resources. The separation prevents collisions when the collection resource has sub-resources itself.

Pagination using cursors

Our APIs contain a lot of resources that provide lists to other resources. With unbound length, it is not reasonable to return an entire list in a single request. We therefore use pagination to split up these lists. Pagination is done using cursors allowing stateless pages. Each page contains a list of links pointing to the previous and next page as well as the first page of the list. A page is identified by the first hit on the page.

The common ground is an elaborated conception, what distributed reporting should be for the diretto platform. The key entity is a document, that is a testimony of an event. A document possess a geo-spatial and temporal source of origin. While documents are abstract entities, there are always at least one attachment appended to it. Further attachments allow enhanced or processed variants of the original piece. Users can apply tags and comments to a document, propose updated time/place origins and vote on all of these items. Key value pairs provide additional tags beneficial for machines and links allow to connect causally related documents.
While this was a rather generic description, here is an example: Alice is eye-witness of an event an takes a photo (document) with her smartphone. She uploads the raw image (attachment), and appends the time and position. Unfortunately, Alice does not have GPS enabled, so the position is inaccurate. Bob is not on-site but accesses the platform via browser. He sees the images and recognizes the exact position. He then proposes an improved position and appends some useful tags. He downloads the image and improves the contrast. He then uploads the outcame as an additional attachment. Other examples for documents are videos, audio recordings, text messages, sensor reports etc.

To make this conception computationally comprehensible, it is described in form of a language-agnostic API. In detail, we have chosen a RESTful approach, based on HTTP. Thus our API is a set of (connected) resources and valid operations on these resources. Different concerns are separated by different APIs. So there is for instance an API that handles the upload, download and storage of raw documents that have been submitted. But handling comments, votes etc. is handled by another API, and so on. This not just modularizes the API, it also allows you to use only subsets of the API, depending on your use case.

Basically, you could start to implement components for the diretto platform by implementing the two sides of the API – the service providers (servers), and the service consumers (clients). However, we offer a middleware that already provides the platform internals, based on the APIs. More precisely, we offer a backend service implementation that represents a service provider. On client side, we offer ready-to-use client libraries so you don’t have to deal with low-level communications.

So relying on our middleware allows you to build your specific reporting application on top of the platform. Whether you are bird-watching or you are going to provide live-coverge of a sports event – you don’t have to start from scratch. Instead, you can select from the diretto platform the parts of the toolkit that you actually need and directly start to develope it.

Task API: http://diretto.github.com/diretto-api-doc/v2/diretto-ext/task.html
Repository:  https://github.com/diretto/diretto-api-doc

In short, users can create tasks, and other users can participate in these tasks. In terms of the diretto platform, a task is a request of specific footage. Reporters may take in part in tasks and contribute required documents as submissions. A task is always bound to a location and a time frame. A title and description define the task and optional tags allow to categorize it. Votes help to prioritize different tasks within the community. Tasks can be commented for exchange of ideas. Finally, every user can submit an existing document as footage for the task. The community can then rate the suitability of the submission regarding the task request. Besides the of directed collection of live footage, the Task API can also be used for specialized search queries. In this case, a task represents a search query and all potential results are submissions. This user-driven search is helpful for queries when only users can reason about appropriate hits by analyzing the documents.

Example 1 – Directed reporting
Scenario: The diretto platform has been deployed for a major sports event, let’s say a marathon.
Spectators are encouraged to upload live photos from their wayside position, thus creating a large collection of different photos from this event. Due to special interest in photos of the current title holder a contender, a task has been created for this. When taking pictures of these runners, a reporter may add the document as a submission to this task.

Example 2 – User-driven search
Scenario: A tsunami has devastated a larger coastal area. In the aftermath, a diretto platform has been deployed in order to collect corresponding media footage. Although there was a major infrastructure breakdown, eyewitnesses had been able to make photos and videos using their cameras or smartphones. A few days later, many of these documents have been uploaded and are now available on the internet.
The diretto platform is used to aggregate these documents combined with temporal and spatial meta data. A task is then created querying for documents that capture the exact moment of the flooding for further analysis. Platform users may now survey all existing document and suggest appropriate footage to the task as submission.

Image by nataliejohnson; cc-by-nc/2.0

Core API
The Core API represents the only mandatory API that is necessary for a diretto platform (although in most cases at least the Storage API will be required as well). The Core API provides access to the common operations like adding user-generated documents and contents as well as query and retrieve methods.

Storage API
The Storage API handles the upload, storage and access of multimedia files on platform. This API is independent of the actual backend storage used.

Feed API
The Feed API provides different news feed formats, including ATOM and KML. A PubSubHubbub publisher node enables push-style notifications of changes.

Streaming API
The Streaming API exposes an event-based notification service. As an alternative to the PubSubHubbub-enabled feeds, the notification streams can help to create real-time applications and services for the diretto platform.

Registry API
The Registry API allows external services to register. This facilitates lookup and discovery of additional services for the clients.

As programming completely generic REST clients is still a long way off – also due to missing availability of powerful semantic representations – it’s unlikely that developers will take this route when implementing clients for your RESTful service. So it is beneficial to have an extensive API documentation, even if you follow the pure REST idea. This not just eases client development, it also helps you to maintain your service as you have to document your stuff anyway.

The popular WADL format tends to be a machine-readable description that helps generating code. For the documentation of the new diretto APIs, we decided to create our own format, that facilitates the creation of high-quality and comprehensive documentations for human readers instead. The XML-based templates can be rendered into various formats, like plain text, XHTML and PDF (using LaTeX).

You can fork the rest-doc-template project at github: https://github.com/berb/rest-doc-template

There are also examples available:

• API Description
• Output

Feel free to fork and contribute!

• Original repository: vmx/geocouch-utils
• Our internal working repository: berb/geocouch-utils

The meta data and user-generated data are stored in another database backend, so the Media Node essentially requires a key-values based storage as backend that can handle BLOBs. In our first version of the Media Node, we have implemented a simple backend that uses the local filesystem. Although this worked well for our experimental deployments, we are considering alternative backends more appropriate for certain use cases.

In the upcoming version 2 release, we are going to introduce pluggable backend connectors. These connectors allow to change the backend storage simply via configuration and facilitate the integration of new backends.

We implemented two backend connectors so far. The first one uses the local filesystem. The second one connects to CouchDB and uses standalone attachments that have been introduced in 0.9. This setup allows a CouchDB-only deployment as backend storage for both meta-data and files.

We are currently working on a connector, that taps into OpenStack Object Storage aka Swift. Such a setup is suitable for large-scale deployments. The swift system provides scalability, fault-tolerance, and allows your storage to grow up even to petabytes. We are also planning to add a Amazon S3 based connector later.

Thus, a part of our team applied for a Karl-Steinbuch scholarship in order to be able to follow up some of these ideas. We also envisioned the benefits of a dedicated platform for distributed reporting in disaster scenarios when combined with collective intelligence algorithms.

Luckily, our follow-up project “diretto.resc” has been granted by the MFG Stiftung Baden-Württemberg as a Karl-Steinbuch scholarship and Benjamin and Tobias will be working on the platform till summer 2011.

Photo of the certificate hand over: Helmut Rau (Minister of the State Ministry, Baden-Württemberg), Tobias Schlecht, Benjamin Erb, Klaus Haasis (MFG Stiftung Baden-Württemberg) and Hans-Günter Hohmann (bwcon)

Image by Ginger Neumann/MFG Baden-Württemberg; CC-by-nc-sa

We’d like to thank the MFG Stiftung Baden-Württemberg for their support and for enabling us to carry on with our ideas.

Other links:

• http://www.doit-online.de/cms.php/do+it.themen/Aktuell?detailid=9013
• http://www.baden-wuerttemberg.de/sixcms/detail.php?id=241648
• http://www.flickr.com/photos/mfg_innovation/sets/72157625453812394/with/5201368239/

When it comes to queries, it is important to repress the mental model of any SQL databases you might have used so far. CouchDB provides a completely different way where you have to write MapReduce-based functions that create ordered lists as view to your data. For more complex queries, including some join-like requests, view collation provides a powerful yet tricky solution. One weakness of CouchDB that can’t be solved even using view collation is the absence of any range queries in continuous spaces. We faced this problem while working on the diretto service implementation and eventually found a proper solution.

In diretto, all documents have a moment where they have been created, or – for continuous media like videos – a moment where the creation has been started. However, it is hard to tell the exact time without properly synchronized clocks in cameras, recorders etc. When a document is received in hindsight by a third person, telling the correct moment might even be harder. So beside of accepting an exact moment, we also provide support for periods, like “that photo has been taken between 9:11 and 9:23″. Now users of the platform can not just suggest alternative values, they can also vote for the information they most likely believe in. Eventually, this should provide a collaboratively created approximation of the correct information.

… with CouchDB

Sounds good in theory, but when it comes to the queries like “give me all documents that have been presumably taken between 9:00 and 9:30″, you’re stranded with regular CouchDB. There is a workaround that divides the time into distinct periods and then emits a key for each segment the document is inside. This might work in our example, but it is obvious that this will emit a lot of keys and might not scale when there are long durations and fine-grained partitionings.

Here is an example document:

{
   "_id": "s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de",
   "begin": "2010-08-05T09:11:52.156Z",
   "end": "2010-08-05T09:23:13.457Z"
}

Map function for a key emission every 5 minutes:

//length of time segment (here 5 min)
var periodLength = (60*5);

function(doc)
{
	if(doc.begin && doc.end)
	{
		//start and end time as UNIX timestamps (seconds, not milliseconds)
		var begin =  Math.round(new Date(doc.begin).getTime()/1000);
		var end =  Math.round(new Date(doc.end).getTime()/1000);

		//calculate first matching segment of period
		var p = (begin - (begin%periodLength));

		//emit key for each matching period
		while(p<=end)
		{
			emit([p, doc._id], null);
			p = p + periodLength;
		}
	}
}

The view then correctly returns:

http://localhost:5984/entries/_design/entries/_view/docsByPeriodList?startkey=[1280998800]&endkey=[1281000193,{}]

{"total_rows":3,"update_seq":2,"offset":0,"rows":[
{"id":"s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de","key":[1280999400,"s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de"]15,"value":null},
{"id":"s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de","key":[1280999700,"s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de"],"value":null},
{"id":"s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de","key":[1281000000,"s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de"],"value":null}
]}

There are the matching 5 minute slots beginning at 9:10, 9:15 and 9:20.

The following sketch illustrates the B-tree containing entries emitted by period (note that the grayed-out key is an exemplary entry for other documents in the view and is not shown in other example outputs.):

… and way better with GeoCouch

We have the same problem for locations, where we also have various suggestions and inaccuarte data. Due to the fact that two-dimensional data (like a WGS84-encoded position) also can’t be indexed efficiently in CouchDB’s B-Trees, we switched to a fork by Volker Mische that is additionally backed by a R-Tree that enables multi-dimensional indexing (currently, it only supports two dimensions, but hopefully it will support more in the future). As a nice side-effect, GeoCouch also allows for spatial searches using bounding boxes. So you can search for spatial features within a limited area. This gave us the idea to apply these functions to our temporal indexing problem. !GeoCouch’s R-Tree is not bound to geographical values (however to two dimensions), so an entry could be any point or rectangle (bounding box) indexed by numerical positions.

GeoCouch’s spatial index expects GeoJSON entries (which are also not bound to any distinct format like WGS84), so we emit our time periods as positions with bounding boxes. The longitudinal values are ignored and set to 0 and the latitudinal values represent the temporal start and end point encoded as time stamps. Thus, we are now able to efficently query all entries within a given period.

Period spatial-based query:

function(doc)
{
	if(doc.begin && doc.end)
	{
		//start and end time as UNIX timestamps (seconds, not milliseconds)
		var begin =  Math.round(new Date(doc.begin).getTime()/1000);
		var end =  Math.round(new Date(doc.end).getTime()/1000);

		emit(
			{
				type: "Point",
				bbox : [0,start,0,end]
			}, null
		);
	}
}

Spatial query using start and end timestamp as range delimiters:

http://localhost:5984/entries/_design/entries/_spatial/entriesByPeriod?bbox=0,1280998800,0,1281000600


{"update_seq":16,"rows":[
{"id":"s-ffc0b6b0-59d4-4a3b-ad36-7ec05e7db1de","bbox":[0,1280999512,0,1281000193],"value":null}
]}

As you can see, GeoCouch does not only allow us to store such entries with ranging values, it also also to query them easily.

But one important restriction to that model is that there is no other message exchange pattern than request/response. Also, such an interaction can only be initiated by the client. As long as there is no incoming request from a client, the server is not able to transer any data to this client. There are several workarounds where a server can push content to a client within an existing application session like long-held unclosed HTTP requests. Also the upcoming WebSocket standard aims at this problem by introducing an easier two-way communication between client and server.

In the real world, there are often scenarios where a server knows that a resource has changed and it might even know which of its clients might be interested in this change, but it cannot publish the information. The only way to this with plain HTTP so far is to configure clients to poll actively. Each client interested in changes must periodically poll the server for changes. A task that almost all of our RSS feed reader do all the time. It is obvious that this neither is performant nor scales very well.

Other technologies like XMPP or most of the message oriented middlewares don’t restrict nodes to the strict roles of requestors and replier. These technologies are predestinated for publish/subscribe flows.

For diretto, we have been facing the problem that on the one hand, we wanted to build our whole architecture on HTTP. On the other hand, we wished real-time notifications for our clients. Thanks to a Google-initiated project called PubSubHubbub, there is a simple, open, publish/subscribe protocol only based on vanilla HTTP.

The trick to PubSubHubbub is the fact that all nodes – publisher, subscriber and relaying hubs are both – HTTP server and client. Thus, the distinction between clients and servers is overcome. Details to the PubSubHubbub technology can be found here on the project’s site.

In the diretto architecture, we implement a publisher service in our feed node, which publishes the creation of new documents and the completed uploads of attachments. And a special client extension provides access to the subscriber functionality, which triggers callbacks for such events.

The following video from Google describes the PubSubHubbub idea in short: http://www.youtube.com/watch?v=B5kHx0rGkec.

Step 1: Acquiring Data

Practically all GPS receivers I know share their data with the rest of the world via a serial interface — the more modern ones with integrated serial-to-usb-converters, of course. Though your mileage may vary, omitting the java.io package and going straight for gnu.io.rxtx will prove likely to save you quite some frustration.

Since you want your GPS information in the NMEA 0183 format, you will need to set the serial interface properties accordingly:

setSerialPortParams(4800, SerialPort.DATABITS_8,
  SerialPort.STOPBITS_1, SerialPort.PARITY_NONE);

Theoretically, the NMEA data now rushing through your console is all you need to parse. To make things more orderly, though, I can recommend the Java NMEA API, which allows targeting of specific NMEA sentences. Reading their documentation is recommended at any rate, if you’re new into GPS data acquisition.

Side note: Should you experience troubles with USB GPS receivers being recognized by your Linux system, but !RxTx shelling out errors like “No such port”, make sure to set the permissions accordingly — chmod 666 /dev/ttyUSB0 and chgrp tty /dev/ttyUSB0 might help.

Step 2: What do we need, anyway?

Once connected, your console will be flooded with NMEA data, probably looking like this:

$GPRMC,101836.000,A,4825.1856,N,00956.8032,E,0.23,226.38,230710,,*07
$GPVTG,226.38,T,,M,0.23,N,0.4,K*68
$GPGGA,101837.000,4825.1857,N,00956.8023,E,1,04,1.4,567.4,M,48.0,M,,0000*5E
$GPGSA,A,3,17,05,08,18,,,,,,,,,8.6,1.4,8.5*36
$GPRMC,101837.000,A,4825.1857,N,00956.8023,E,0.57,292.18,230710,,*09

Intimidating as this might look, it’s all you need to determine your position. Anything starting with $GP is GPS data according to the NMEA 0183 specification, and the following three characters further specify what kind of information the sentence contains.

All we will look into from now is the GGA sentence, since it contains everything we need. Seperated by commas, we find:

• Current time in UTC
• Latitude and identifier N or S
• Longitude and identifier E or W
• Quality of measurement (0 == invalid, 1 == valid GPS, 2 == valid DGPS)
• Horizontal Dilution of Precision
• Height above sea level, with unit
• Height over geoid, minus height over ellipsoid, with unit
• Checksum

Apart from the date, the GGA sentence delivers everything we want. All that’s left to do for us is splitting and translating the data.

Step 3: Translating the coordinates

Translating? Yep. The NMEA sentences contain information like 4825.1857,N,00956.8023,E, which translate to 48° 25.1857′ north latitude and 9° 56.8023′ east longitude. We, however, do not want to calculate in degrees, minutes and seconds, but decimal fractions, like 8.4197616 and 9.946705. Hence, translating. Yes.

First of all, we need to split our sentences into their respective parts. Some tutorials recommend the use of !StringTokenizer to do so, which is not the best of ideas. When your GPS receiver lost its fix — for instance in a tunnel — the GGA sentence looks like this:

$GPGGA,103927.819,,,,,0,00,,,M,0.0,M,,0000*58

To avoid having to handle situations like this, the sentence can be split along all the commas with split(",").

After this operation, the position of all information bits is well defined. Should we operate without a valid GPS fix, sentence_parts[6].equals("0") is true.

Let’s assume we have a valid GPS fix and want to translate our coordinates. Despite their using StringTokenizer, this tutorial helps us with the calculation. “raw_latitude” is sentence_parts[2], “lat_direction” sentence_parts[3], and so on.

So, now we have our position. An approximation, at least. More to come about how to find out the precision of our fix. Stay tuned

The client library comes in two flavors – a basic version and an extended one that is PubSubHubBub-enabled. The latter requires a public HTTP server endpoint but allows to register callback functions. These functions will be executed almost in real-time as soon as the server publishes certain events, like the complete upload of a new document.

While most of the regular client applications – including mobile clients – will only need the basic client library, there are also usages for the !PubSubHubBub-aware version. For instance, dedicated headless clients might subscribe for new documents and directly download and process them in some way. This takes off a lot of work from the server and provides a clear path for feature extensions. Also our rich web application takes advantage of this mechanism in order to display new documents on the maps in real time.

The Java client is basically a client-side implementation of our RESTful web service. Therefore, we used Restlet, a REST framework for Java. It provides useful abstractions of the low-level HTTP communication and maps the representations/resources of a RESTful architecture to appropriate classes. For the underlying HTTP communication, we use Apache’s HttpClient library. The JSON serialization/deserialization relies on Jackson, a high performance library that allows various mappings, including a mapping between unnotated POJOs and JSON structs. Beside that, we use a lot of other libraries, like many of the Apache Commons libraries and JodaTime for handling time data.

For the subscriber-side implementation of our PubSubHubBub-enabled client, we developed our own subscriber library, because the existing one did not fit our requirements. It uses Jetty as lightweight internal webserver for receiving notification pings. This library has been developed apart from the main client source and has been released on github: java-sub-pubsubhubbub

One major problem we ran into was the difficulty of mapping our geo-data into B-Tree-based views for location searches and proximity lookups. It is not just nasty to use for this, but also highly inefficient. Thankfully, there were already other people having this issue and , a student from the University of Augsburg, is currently developing a CouchDB extension for spatial queries as part of his diploma thesis. In his fork, he has implemented a spatial query mechanism based upon a R-Tree, a highly efficient index for multidimensional queries, and range queries. GeoCouch and diretto both follow the GeoJSON specification for representing positioning data in JSON. We are looking forward to see the cool spatial features in the main branch of CouchDB soon!

Our first choice was Restlet, a Java-based framework for REST services. But we soon realized that converting CouchDB results to Java objects and the back to JSON was a tremendous effort, even with helper libraries. By that time we quite accidentally discovered node.js, a framework for scalabale network programs. The interesting part for us was the fact, that node.js applications are entirely written in JavaScript.

After a comparison between a first example service implementation written in Restlet and node.js, we realized that we could minimize the service implementation code when using node.js. Another great advantage of node.js was it’s strictly evented and asynchronous i/o design. This allows node.js applications to handle thousands of requests concurrently without any bottlenecks due to blocking operations. Implemented on top of Google’s v8 JavaScript engine, node.js provides impressive performance contrary to objections some people have when thinking about JavaScript.

The next step was to select appropriate libraries for our service, especially a CouchDB library and helper libraries for implementing RESTful services in node.js. For both requirements, we took great libraries developed by cloudhead – cradle as a high-level, caching, CouchDB library and journey for JSON-based services and HTTP request routing. Additionally, we use Mu as a Mustache template engine in node.js for generating non-JSON output like our Atom or KML feeds.

Our service implementations are now implemented also as node.js libraries and separated into several components for higher reusability. In the end, we wrote three different node applications, one for our API service implementation, one for media upload & delivery (rather an enhanced static webserver) and for feed export and PubSubHubBub publishing.

All libraries and implementations will be released open source as soon as we finish our first stable release candidate.

Scalable Server Cloud

The server(s) contain five distinct components. These components can be deployed in many different ways. In simple cases, they can be placed on one single machine. In a heavy use scenario, all of them they can be replicated for load balancing. We will have a look at scalability in a blog entry soon.

ApiNode
The API node represents the endpoint of our diretto RESTful webservice.

MediaNode
The media node is a webserver that handles incoming file uploads, organizes storage and provides web-based access to uploaded items.

FeedNode
The feed node provides web access to Atom feeds. It is also PubSubHubBub publisher that notifies hubs as soon as new content is available. Therefore, it monitors the meta data storage for changes and bumps the PubSubHubBub notification process.

Meta Data Storage
The meta data storage is used for all meta data of uploaded items and other user generated data like tags, comments etc.

Media Item Storage
The media item storage is responsible for storing all uploaded and gathered documents of the platform.

RESTful Webservice

The service API is based upon the REST paradigm, hence we provide a RESTful webservice implementation. We are using JSON for data exchange and encode geo data with GeoJSON. For the PubSubHubBub nodes, we also use the Atom syndication format for feed data.

External Services

These services provide additional functionalities that are not included in the original service. Such facilities can be used by clients, if they are enabled for.  Conceptually, external services are service instances that are separated and isolated from the original service.
A simple example for an external service is a UUID hashing service. The platform is using UUIDs for identifiying documents. However, this might not be very handy for humans. An external service might provide shortened IDs for the original UUIDs. Now a client can use these shortened IDs by accessing the external services. Users of the client will then only see short IDs. Internally, the client uses the UUID hashing service for resolution when interacting with the original server, where UUIDs are needed.

Special Clients & Tools

Beside external services, special clients are first class instances for extending the diretto service. Unlike external services, these tools don’t provide a service endpoint by their own. Instead, they rely on the original service for interaction. Tools might also be PubSubHubBub subscribers, which allows them to react on new content instantly.
A good example for such a tool is an automated image resizer. The server only stores an original image when a photo has been uploaded. Now a client can subscribe for incoming images. Thus, it will be notified, as soon as a new image arrives. Then the client can download the image, resize it and upload the altered version as an attachment to the original document.
It is obvious that this concept not just takes off a lot of load from the servers. It also the starting point for many customized clients.

Web Application

The web application is a special client which renders a web view to its own clients. It allows user to interact with the service without using the RESTful API directly. Instead, users access this rich web application.

Smartphone Clients

Smartphone clients are important clients for instant content upload. They provide a leightweight implementation that adapts to the mobile usage context.

Wearable Embedded Clients

Our wearable client is a headless unit that allows the bearer to connect “offline devices” like digital SLR cameras.

Only use open standards, formats and protocols

For each part of the system, we rely on existing standards. This not just ensures that all used technologies are suitable for productive usage, it also eases integration and extension of the system.

The standards we use include HTTP for transport, REST for the webservices, JSON for data exchange, GeoJSON for geo-enabled data, Atom for feed data and the PubSubHubBub protocol for real time web.

HTTP as the only protocol between peers

We tried hard not to use any other protocol but HTTP for transport. HTTP has shown in the past that it is a very powerful protocol that scales well. Thus, it is used in the diretto platform between every single peer. Even servers use HTTP for communicating with databases.

The absence of proprietary protocols or other protocols simplifies communication, distribution and extensions. Thanks to the REST paradigm, HTTP is also the basis for the webservices.

Keep scalability and distribution in mind

When designing our service architecture, we focussed on building a distributable architecture instead of a monolitihic one. On the one hand, the server is no single application. It consists of several components that can either be run on a single host or be deployed onto multiple machines.

On the other hand, we only integrated the core functionalities into the server. Other features should be run externally. For instance, the generation of thumbnails for new photos is not built into the server. Instead, a designated client can register for notifications of newly available images, then download them, create a resized version and upload them. This not just takes off load from the server, it also advertises for external service extensions by design.

The primary goal of the Distributed Recon/Reporting Transceiver Toolkit (diretto) project is the creation of an easy-to-use infrastructure and toolset for distributed on-site media reporting and collaborative event coverage in realtime as a open source solution. The platform empowers various collocated users to participate in the reporting, but also integrates remote viewers using feedback functions.

For mobile reporting, the system offers different client applications for various internet-enabled devices. However, it also provides a solution for embedded photography reporting using regular digital cameras by introducing intermediate uplink nodes. It also addresses typical problems faced by distributed mobile collaboration like data propagation under low bandwidth or with unavailable uplinks. Typical usage environments are large-scale public events or disaster response situations.

Project Background

The diretto project is descended from an university project at the University of Ulm, Germany.
The original project design was elaborated in the winter term 2009 by a team as part of the elective course Ubiquitous Computing at the Institute of Media Informatics. In the summer term 2010 two teams will implement various parts of the system. The Ubiquitous Computing team will implement the basic server infrastructure and several applications for mobile usage. The Interactive Systems team will create a web-based application as a frontend for remote users.

Components

The diretto system is highly modularized. The diretto API represents the core of the system. All applications and software modules are implemented against this API.

The diretto server is responsible for the server-side implementation of the API and for the web-based service provision and accessibility. This includes the solid storage of gathered media entites and corresponding meta data.

Diretto clients provide access to the system for the users for various devices and scenarios. Possibile implementations range from lightweight smartphone applications to web-based clients and highly customized solutions for embedding additional devices.

Smartphone clients allow people on-site to report in media items like snapshots, video snippets or audio material. These clients also enable people to see and comment the reports and entities reported in by other people nearby.

The web application enables remote users to participate in the process by observing, assessing and evaluating media items submitted to the system. Such feedback also supports the on -site users.

In order to integrate detached media devices such as digital cameras, a special uplink device has been designed. This portable uplink device allows the bearer to attach wired or wireless devices. New content will be fetched and and submitted directly to the server.

Other client tools can add additional functions like automated content analyzing or the export of event timeline feeds into the RSS format.

Features

Open Source – The complete platform is available as open source. This guarantees continuity and availability, but also allows the implementation of extended or derivative solutions.

Extensibility – The API does not define how clients must be implemented. It only describes how gathered data must be exported to the server and communication between clients and the server is supposed to be. This allows the implementation of a lot of different clients with specialized purposes and customized features.

Versatility – The API does not impose any restrictions on media types. Thus, new formats can easily be integrated.

Scalability – The diretto platform is designed to cope with a lot of data in parallel. This allows the usage even in scenarios where a huge number of people use the system and report in data simultaneously.

Easy Deployment – The platform and all applications have been designed with a focus on easy deployment. Most of the applications run on regular devices and the server can be set up on commodity hardware. Thus, users can easily host their own sessions or pick up an application and immediately participate in a reporting scenario.

Lightweight – In order to cope with the problems of mobile reporting like low bandwidth, the diretto API is built on lightweight technologies like HTTP, REST and JSON.

Use Scenarios

Diretto is designed as a versatile and flexible platform for distributed mobile reporting. Thus, diretto can be used in various different scenarios. Three exemplary scenarios are described here, although there are a lot of other potential usages.

Being equipped with suitable hardware or diretto-enabled extensions, journalists are able to report in different media types on-site and virtually in realtime to the online reporting system. Both single journalists and collocated teams can be embedded into public events even of larger scales. Additionally to professional journalists, one can imagine regular citizens with smartphones or other devices contributing to the collection of media items of such an event.

Introducing the diretto platform for emergency services can improve response times and resuce efforts. The ability to record and instantly submit data from a scene by deployed units assists a (remote) command, that filters and evaluates incoming data and take appropriate actions.

Even civil right groups can use diretto for monitoring and documenting their public demonstrations and thus ensure appropriate behaviour of police and law enforcement agencies.

Roadmap

The initial project outline has been elaborated in the winter term 2009. Until spring 2010, the initial version of the API will be published. During the summer term 2010, all important application components will be created as a reference implementation. This will also include field tests in different scenarios.
Finally, the whole project will be released as open source to the public.

Related Work

There are some approaches towards similar platforms with both academic or government-funded background (i.e. CoMedia or the indect Project). Also non-academic services like Ushahidi, Twitter, Flickr or qik have parts in common with our platform. Our main goal is the design of a platform, that incorporates all of the necessary features for mobile distributed and collaborative media reporting in one unified system.