Waiana service module

This is an upcoming feature that is not available in the current release of Wandora. The Waiana service will be part of release 2014-08-20.

Waiana service module implements a local topic map storage with an API compatible with the Maiana API. Maiana and Maiana API build up a topic map storage created and hosted but the 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

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

{
  "parameters":{
    "command":"show_local_file_list",
    "api_key":"api-key-of-user"
  }
}

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

{
  "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",
    "api_key":"api-key-of-user"
  }
}

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

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

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"
}

Limitations

• At the moment Waiana API doesn't use API keys and doesn't authenticate users! Thus, don't open up your topic maps storage to the world!