There are some rumors that an API that completely follows the REST paradigm does not need a documentation as a single entry point URI is all you need to get started. The uniform interface, self-descriptive representations of resources and linked resources through hypermedia encourage an interaction flow very similar to human web browsing.
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:
We stick to GeoCouch also in our upcoming v2, where we are currently working on. It provides us a scalabale storage that can also handle spatial queries efficiently. We recently joined Volker Mische, Max Ogden and David Thompson in an effort to create a repository that collects common GeoCouch functionalities. This currently includes a KML Feed/GeoJSON FeatureCollection export, radius queries, spatial clustering and some helper scripts, but more stuff will be added soon.
Feel free to fork and contribute!
A core part of the diretto reporting platform is the Media Node. One or more instances of this service are responsible for storing the actual media files, processing incoming uploads and then serving these media files to clients.
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.
Although the diretto project has now ended as a university project, we are happy to announce that the project will be continued. Within the last year, we designed and implemented a basic platform for distributed reporting, including a rich web frontend and experimental mobile clients. However, not all of our initial ideas could have been implemented due to the lack of time. In fact, we discovered many additional ideas for the project during the development.
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:
This website will now be used for hosting our blog, documentations and other project-related data.
2012 diretto Project Team