API Controller

Call

The API is awaiting your calls at http://maiana.topicmapslab.de/api and is able to process a JSON object.

This object should consist of:

{
  api_key: the api key of the user (see the profile),
  parameters: a Hash consisting of the command and command specific parameters,
  data: additional data, if necessary
}

An example call should look like

curl -H "Content-Type: application/json" -d 
'{"api_key": "your_api_key", "parameters": {"command": "show_local_file_list"}}' 
-X POST http://localhost:3000/api -i

Note that the Maiana-API accepts json requests only (i.e. ContentType is application/json).

Response

The response is always a JSON object:

{
  code: [response code, 0==OK, 1!=OK],
  msg: "[more specific explanation of the error or a success message]",
  data: [data that has been requested]
}

Prechecks

The API performs several pre-checks to make sure that the request is in the form it expects it be.
In detail, it checks:
  • whether the request is a json request (i.e. the content type is "application/json",
  • whether the api_key exists,
  • whether a parameters block is set and
  • whether a valid command is given in the parameters block.
If one of the above checks fails, the response code of the answer will be "1" and the messages are(in the same order)

Actions

The following actions may be executed:

create_topic_map
update_topic_map
delete_topic_map
download_topic_map
show_topic_map_list
show_container_references
edit_container_references
execute_tmql
search_endpoint
create_local_file
update_local_file
delete_local_file
show_local_file_list
download_local_file

1. create_topic_map

To create a topic map, the user needs to specify the name, short name, privacy settings (default: false, optional) and the topic map source file (if any). The privacy settings are:
  • is_public: everyone may see the map (default: false)
  • is_downloadable: everyone (not only the owner) may download and query the map (default: false)
  • is_schema: the map may be used as schema to validate other maps against it (default: false)

In case the topic map to be created is a container, no source file is needed, hence if existent, it will be ignored.

For backwards compatability, the method create_local_file is still accessible and uses LocalFile as endpoint_type.

Question:

parameters = {
  command: "create_topic_map",
  endpoint_type: "[endpoint type]"(available types by now are LocalFile and Container, LocalFile is default, optional),
  short_name: "[short name of the map]",
  name: "[name of the map]",
  is_public: boolean(default false, optional),
  is_downloadable: boolean(default false, optional),
  is_schema: boolean(default false, optional, true not allowed for containers)
}
data = serialized topic map as String (xtm, ctm, jtm or ltm, otional)

Answer:

{
  code: 0,
  msg: "Successfully created topic map named '[name]'",
  data: "[url to endpoint]" 
}

2. update_topic_map

Most of the parameters are identical to create_topic_map. The action is called update_topic_map and you may specify the owner of the map (because later, also editors may update a map they don't own). Data is optional.

For backwards compatability, the method update_local_file is still accessible and uses LocalFile as endpoint_type.

Question:

parameters = {
  command: "update_topic_map",
  endpoint_type: "[endpoint type]"(available types by now are LocalFile and Container, LocalFile is default, optional),
  short_name: "[short name of the map]",
  name: "[name of the map]",
  is_public: boolean(default false, optional),
  is_downloadable: boolean(default false, optional),
  is_schema: boolean(default false, optional, true not allowed for containers),
  owner: [login of the owner of the map, optional]
}

Answer:

{
  code: 0,
  msg: "Successfully updated topic map named '[name]'",
  data: "[url to endpoint]" 
}

3. delete_topic_map

This command removes a map from Maiana. Here, only the command name delete_topic_map and the short name of the map to be deleted are needed.

For backwards compatability, the method delete_local_file is still accessible.

Question:

parameters = {
  command: "delete_topic_map",
  short_name: "[short name of the map to be deleted]" 
}

Answer:

{
  code: 0,
  msg: "Successfully deleted local file" 
}

4. show_topic_map_list

Here you only need to specify the command show_topic_map_list. The response includes all maps that are either public or visible to the user or owned by the user.
The answer can also be given in jtm format, but be aware that metadata like is_schema, is_downloadable and alike is not included in this fragment. This is WIP and should be considered beta.

For backwards compatability, the method show_local_file_list is still accessible.

Question:

parameters = {
  command: "show_local_file_list",
  format: "json|jtm" (default json, optional)
}

Answer:

{
  code: 0,
  data: 
  [
    {
      name: "[name of the map]",
      short_name: "[short name of the map]",
      owner: "[owner of the map]",
      is_schema: boolean,
      is_editable: boolean,
      is_downloadable: boolean
    },...
  ]
}

5. download_topic_map

With this command a map may be serialized and downloaded. The required parameters are the command download_local_file and the "short_name" of the desired map.

For backwards compatability, the method download_local_file is still accessible.

Question:

parameters = {
  command: "download_local_file",
  short_name: "[short name of the map]",
  owner: "[login of the owner]" (default api_key user, optional),
  format: "[format]"(default xtm2.0, optional)
}

Answer:

{
  code: 0,
  data: [serialized topic map]
}

6. show_container_references

With this command, references of a container may be queried. The required parameters are the command show_container_references and the "short_name" of the desired container.

Question:

parameters = {
  command: "show_container_references",
  short_name: "[short name of the container]",
  owner: "[login of the owner]" (default api_key user, optional),
  format: "json|jtm" (default json, optional)
}

Answer:

{
  code: 0,
  data: 
  [
    {
      name: "[name of the reference]",
      short_name: "[short name of the reference]",
      owner: "[owner of the reference]",
      is_schema: boolean,
      is_editable: boolean,
      is_downloadable: boolean,
      is_active: boolean
    },...
  ]
}

OR

{
  code: 2,
  msg: "You don't have access to [# invisible references] references in this container.",
  data: 
  [
    {
      name: "[name of the reference]",
      short_name: "[short name of the reference]",
      owner: "[owner of the reference]",
      is_schema: boolean,
      is_editable: boolean,
      is_downloadable: boolean,
      is_active: boolean
    },...
  ]
}

7. edit_container_references

With this command, references of a container may be edited. The required parameters are the command edit_container_references, the "short_name" of the desired container, the "action" of editing, i.e. one of add, remove, activate, deactivate and the "references" on which an action will be executed.

Question:

parameters = {
  command: "edit_container_references",
  short_name: "[short name of the container]",
  owner: "[login of the owner]" (default api_key user, optional),
  action: "add|remove|activate|deactivate",
  references: [
                {
                  short_name: "[short_name of the reference]",
                  owner: "[owner of the reference]" 
                },...
              ],
  format: "[format]"(default xtm2.0, optional)
}

Answer:

{
  code: 0,
  msg: "Successfully executed action '[action]' in container '[short name of container]'." 
}

OR

{
  code: 2,
  msg: "Action '[action]' partly finished in container '[short name of container]', errors were: [error messages]" 
}

8. execute_tmql

This way a TMQL query may be executed. If the user is owner (editor) of the map, TMQL update statements are enabled. The required parameters are the command name execute_tmql, the short name of the map and the query as String. The response shows, whether the query has been executed successfully, or not.

Question:

parameters = {
  command: "execute_tmql",
  short_name: "[short name of the map]",
  query: "[TMQL query]",
  owner: "[login of the owner]"(default api_key user, optional),
  enable_updates: boolean (enables theTMQL update statements, default false, optional)
}

Answer:

{
  code: 0,
  msg: "Successfully executed TMQL Query '[query]'" 
  data: The query results serialized in JTMQR format
}

The data block of normal TMQL queries contains the results for this query. For TMQL update statements, the data block contains the number of affected constructs. However, the data block is always in QRJTM format. You can find additional information about the JTMQR format in the JTMQR Specification.

9. search_endpoint

You may execute the search on any endpoint (i.e. topic map) that is visible for your api key. The mandatory parameters are short_name and query.

Question:

parameters = {
  command: "search_endpoint",
  short_name: "[short_name of the map]",
  query: "[Search Query]",
  owner: "[login of the owner]"(default api_key user, optional)
}

Answer:

{
  code: 0,
  msg: "Successfully executed Search Query '[query]'" 
  data: 
  [
    {
      name: "[name of the resulting topic]",
      identifier: "[identifier of the resulting topic]",
      score: "[score of the resulting sopic]",
      is_topic_type: boolean [Denotes, whether the resulting topic is used as a topic type for other topics or not]
    },...
  ]
}

Corresponding error messages

So far, only the successfull response messages have been described. If the call failed, you will see:

{
  code: 1,
  msg: "[Description of the error]" 
}