View source for Waiana service module

Waiana service module implements a local topic map storage with an API compatible with the [http://projects.topicmapslab.de/projects/maiana/wiki/API_Controller Maiana API]. [http://maiana.topicmapslab.de/ Maiana] and Maiana API build up a topic map storage created and hosted but the [http://www.topicmapslab.de/ Topic Maps Labs]. As the Topic Maps Labs is not really working anymore, the status of Maiana and it's API are more or less vague. The Maiana has been broken for several years. Wandora originally supported Maiana API and allowed import and export of topic maps between Maiana and Wandora. The Waiana service module has been implemented to infuse new life into the import and export features, already implemented. Although the Waiana doesn't support topic map browsing but the storage API only, it is probably useful if the user wants to set up a shared topic map storage.

== Waiana API ==

The Waiana API implements a local topic map storage. API's service handle is 

 http://127.0.0.1:8898/waiana/

Supported operations of API are

* List topic maps in storage
* Upload topic map into the storage
* Download topic map from the storage
* Delete topic map in storage
* Stream topic map from the storage

Each operation and operation specific parameters are submitted to the API as a JSON structure. The JSON structure contains a value for key '''command'''. This command is the main switch for different operations. Similar JSON structure requests were supported by the original Maiana API too. Addition to the JSON formatted requests, Waiana API accepts REST requests where URL parameters are used instead of JSON key-value pairs.

Next chapters describe both API requests and responses for all these operations.

== List topic maps ==

The JSON formatted request for listing topic maps in storage is 
 {
   "api_key":"api-key-of-user",
   "parameters":{
     "command":"show_local_file_list"
   }
 }

The REST formatted request for listing topic maps in the storage is

 http://127.0.0.1:8898/waiana/?command=show_local_file_list&apiKey=api_key

Command '''show_topic_map_list''' or '''show_local_topic_map_list''' can be used instead of '''show_local_file_list'''.

The Waiana API replies with a response that is JSON formatted data structure similar to

 {
   "data":[
      {
        "is_schema":false,
        "is_public":true,
        "is_downloadable":true,
        "is_editable":true,
        "name":"test topicmap",
        "short_name":"test",
        "owner":"anonymous"
      }
   ],
   "code":0
 }

Where each topic map has one JSON object in the data array. Each topic map is associated with several boolen flags, a display name and a short name and an identifier of the topic map owner.

== Upload topic map ==

The JSON formatted request for uploading a topic map into storage is 

 {
   "api_key":"api-key-of-user",
   "parameters":{
     "command": "create_local_file",
     "short_name": "short-name-of-the-topic-map",
     "name": "long-name-of-the-topic-map",
     "is_schema":false,
     "is_public":true,
     "is_downloadable":true,
     "is_editable":true
   }
   "data":"the-topic-map-data-in-XTM-2-format"
 }

Similarly, the REST formatted request contains an URL parameter for each key-value pairs of the JSON.

If the topic map storage successfully saved the topic map, the response contains JSON structure similar to the

 {
  code: 0,
  msg: "Successfully created topic map 'topic-map_name'.",
  data: "http://127.0.0.1:8898/waiana/?command=stream&shortName=short_name"
 }

Where data key holds a direct download URL to get the XTM data. If the storage failed to save the topic map, the '''code''' value is non-zero integer and '''msg''' value contains short error message.

== Download topic map ==

To download a topic map in JSON response format, the JSON formatted request is

 {
   "api_key":"api-key-of-user",
   "parameters":{
     "command": "download_topic_map",
     "short_name": "short-name-of-the-topic-map"
   }
 }

The REST formatted request contains an URL parameter for each key-value pairs of the JSON:

 http://127.0.0.1:8898?command=download_topic_map&shortName=short-name-of-the-topic-map&apiKey=api-key

If the storage contains topic map and the user has sufficient read rights, the JSON response is

 {
  code: 0,
  data: "topic-map-in-xtm2-format"
 }


== Delete topic map ==

To delete a topic map in storage, the JSON formatted request is

 {
   "api_key":"api-key-of-user",
   "parameters":{
     "command": "delete_local_file",
     "short_name": "short-name-of-the-topic-map"
   }
 }

Alternative REST formatted request is

 http://127.0.0.1:8898?command=delete_local_file&shortName=short-name-of-the-topic-map&apiKey=api-key

If the storage contains topic map and the user has sufficient delete rights, the JSON response is

 {
  code: 0,
  msg: "Successfully deleted topic map 'topic-map-short-name'."
 }

== Stream topic map ==

Streaming topic map resembles downloading topic map but returns the topic map data only. The response has no JSON container but the raw data of topic map. Exceptionally the stream request has no JSON formatted alternative bu a REST formatted request only. The REST formatted request is

 http://127.0.0.1:8898?command=stream&shortName=short-name-of-the-topic-map&apiKey=api-key&format=JTM|XTM2

The format parameter can be either XTM2 or JTM and selects the response format. As the storage uses XTM2 as the internal data format, Wandora transforms the topic map into JTM format each time the topic map is requested in JTM format. This transformation may be a computation intensive operation.

As said above, the response contains topic map data if the topic map exists and the user has sufficient read rights.

== The topic map storage ==

Waiana stores topic maps into the '''resources/server/waiana/topicmaps''' folder in XTM2 format. The filename is equivalent to the short name of topic map. All harmful characters are filtered out of the short name to prevent hacking. All metadata related to topic maps is stored in a '''resources/server/waiana/topicmaps_data.json''' file. It is the actual database of stored topic maps.

By default the Waiana storage contains one test topic map.

== Example 1 ==

In this example, the Wandora user uses '''Import topic maps from Waiana''' feature to import the test topic map from Waiana storage into the Wandora application.


[[File:waiana_example1_1.gif|center]]


[[File:waiana_example1_2.gif|center]]


[[File:waiana_example1_3.gif|center]]


[[File:waiana_example1_4.gif|center]]


[[File:waiana_example1_5.gif|center]]


== Example 2 ==

In this example the Wandora user has extracted tweets from Twitter using hash tag #opendata. The user exports the layer stack to the Waiana using '''File > Export > Export topic map to Waiana'''. Finally the user resets Wandora and imports the topic map from Waiana back to the Wandora.


[[File:waiana_example2_1.gif|center]]


[[File:waiana_example2_2.gif|center]]


[[File:waiana_example2_3.gif|center]]


[[File:waiana_example2_4.gif|center]]


[[File:waiana_example2_5.gif|center]]


[[File:waiana_example2_6.gif|center]]


== Limitations ==

* At the moment Waiana API doesn't use API keys and doesn't authenticate users! Don't open up your topic maps storage to the world!
* FIXED: <strike>Round tripping a topic map to/from Waiana may change some unicode characters. This is a bug, we are working with. Don't use Waiana as a master storage if your topic map contains exotic unicode characters!</strike>