[[PageOutline]]

= API for Wordnet server =

This API is used for DEB dictionaries that have the class ''!WordNet'' selected in the [WebAdminInterface administration interface]. Nearly the same API is also used for specific classes CdbID, CdbLU and !CdbSynset in the Cornetto server.

Replace ''servername'' with actual address of the server.

For more info about JSON, see http://www.json.org/

API [WordNetApiPhp usage example] in PHP.

The [http://deb.fi.muni.cz/debvisdic.xsd DEBVisDic format XML schema] is described in more details in WordNetFormat.

== Web interface ==

Open ''servername''/''dictionary''?action=listPreview in browser. Accepts the same queries as DEBVisDic.

== JSONP support ==

Every function accepts argument ''callback''. If specified, response is modified to support JSONP.

== Getting the list of available dictionaries for the user == 

'''Request:''' ''servername''/doc?action=connect

'''Response:''' JSON encoded hash with following structure

{{{
{
  "dicts" => {
    ''client_package_id'' => {
      "id"    => ''client package id'',
      "code"  => ''dictionary code'',
      "name"  => ''dictionary name'',
      "access" => ''access rights r/w'',
      "dicslookup" => ''array of package names to allow lookups to'',
      "eqtags" => ''array of eqtags+dictionaries'',
      "dicsreload" => ''array of dictionaries to refresh'',
      "key" => ''dictionary key tag'',
      "indexes" => ''indexed elements''
    }
  }
}
}}}

[WordNetApiOld Older version] used ''init'' action, now obsolete.

== Dictionary Search ==

'''Request:''' ''servername''/''dictionary_code''?action=queryList&word=''search_query''[&add_def=''true/false''][&maxres=''number''][&show_toomany=''true/false'']

 search_query::
  search query, must be URL encoded UTF-8
 add_def::
  optional parameter, if set to true, synset definition is part of response
 maxres::
  optional parameter, number of maximum results returned (default 100)
 show_toomany::
  optional parameter, if set to true and the number of results is higher then ''maxres'', the answer contains one more result with `value: "..."` and `label: "..."`

'''Response:''' JSON encoded array of hashes with following structure

{{{
 {
   "value" => ''entry ID'',
   "label" => ''information about an entry, depends on dictionary, usually contains PoS, literals'',
   "definition" => ''synset definition, only included if add_def=true''
 }
}}}

'''Query types:'''
 * ''word'' - search for entries containing whole word in literals
 * ''word:'' - search for all different senses of literal exactly matching ''word''
 * ''word:number'' - search for exact literals with sense number (possibly more POS)
 * ''[.*]word[.*]'' - search for word substring - .* can be put at the beginning/end of the word or at both of them (N.B. that full regular expressions are not supported at the moment)
 * ''xml_element=value'' - search for value of xml_element, for example SYNSET.POS=n
 * ''xml_element=dictionary_code2:entry_id2:xml_element2'' - search for xml_element with value from xml_element2 of entry_id2 in dictionary_code2

== Query entry information ==

'''Request:''' ''servername''/''dictionary_code''?action=runQuery&query=''entry_id''&outtype=''output_type''[&arg=''argument''][&nojson=1][&default=1][&expand_rels=1][&reldics=''wordnet_list'']

 entry_id::
  ID of displayed entry
 output_type::
  output type of entry, possible values:
 * plain - plain form of XML entry from database
 * xml - coloured, foldable XML representation for display in browser
 * lmf - synset in LMF format
 * html - HTML representation of entry, use default XSLT template, it's possible to specify other template with optional ''arg'' argument
 * tree - array representation of tree, ''arg'' specifies tree direction - ILR for normal tree, RILR for reversed tree
 * editor - hash representation of XML for editor tab
 * rels - searches in ''wordnet_list'' for all synsets that have ELR link to ''entry_id'' and link type 'EQ_Synonym', 'EQ_Near_Synonym', 'EQ_Has_Hyperonym', 'EQ_Has_Hyponym'. Returns array of hash representation.

 arg::
  depends on output_type. For ''html'' optionally specifies other than default template. For ''tree'' specifies tree direction.
 nojson::
  by default response is JSON encoded, by setting nojson=1 response is not encoded
 default::
  optional argument for html output type - with default=1 HTML is displayed with default styles, otherwise style set in client is used
 expand_rels::
  optional argument for editor output type - with expand_rels=1 more details about ILR are included (definition, literals)
 wordnet_list::
  mandatory argument for rels output type - comma separated list of wordnet codes, define in which wordnets to search for synsets

'''Response:''' by default JSON encoded, depends on output type

== Display tree of an entry ==

'''Request:''' ''servername''/''dictionary_code''?action=runQuery&outtype=tree&query=''entry_id''&arg=''argument''

 entry_id::
  ID of displayed entry
 arg::
  specifies tree direction - ILR for normal tree, RILR for reversed tree

'''Response:''' JSON encoded array with tree structure (same as for basic tree in display) - selected entry and its parents



== Display subtree of an entry ==

'''Request:''' ''servername''/''dictionary_code''?action=subtree&query=''entry_id''&arg=''argument''[&rel_type=''relation_type''][&details=''details'']

 entry_id::
  ID of displayed entry
 arg::
  specifies tree direction - ILR for normal tree, RILR for reversed tree
 rel_type::
  optional parameter, used to limit response only to relations of specified type
 details::
  optional parameter, for details=1 add g_syn, definition, for details=2 add g_syn, definition, literal array

'''Response:''' JSON encoded array with tree structure (same as for basic tree in display) - only direct descendants of entry are returned

== Display full subtree of an entry ==

'''Request:''' ''servername''/''dictionary_code''?action=fullsubtree&query=''entry_id''&arg=''argument''[&rel_type=''relation_type''][&details=''details'']

 entry_id::
  ID of displayed entry
 arg::
  specifies tree direction - ILR for normal tree, RILR for reversed tree
 rel_type::
  optional parameter, used to limit response only to relations of specified type
 details::
  optional parameter, for details=1 add g_syn, definition, for details=2 add g_syn, definition, literal array

'''Response:''' JSON encoded array with tree structure (same as for basic tree in display) - display all descendants of entry


== Save entry ==

'''Request:''' ''servername''/''dictionary_code''?action=save&id=''entry_id''&data=''encoded data''

 entry_id::
  ID of saved entry
 encoded data::
  JSON and URL UTF-8 encoded hash representation of an entry (same as returned for ''editor'')


== Delete entry ==

'''Request:''' ''servername''/''dictionary_code''?action=delete&id=''entry_id''

 entry_id::
  ID of entry

== Next sense number ==

'''Request:''' ''servername''/''dictionary_code''?action=nextSense&literal=''literal''

 literal::
  literal that you want to check

'''Response:''' (JSON encoded) recommended_sense = number of the next free sense number for given literal

== "Translate" synsets ==

'''Request:''' ''servername''/''dictionary_code''?action=translate&query=''search_query''&target=''targetWN''

 dictionary_code::
   source language

 search_query::
  search query, must be URL encoded UTF-8, same as for "Querying dictionary"

 target::
  target language, wordnet dictionary code

'''Response:''' (JSON encoded) arrays "original" and "translated" with the list of synsets in source and target language (same structure as for "Querying dictionary")

== Information & statistics ==

=== Relations ===

'''Request:''' ''servername''/''dictionary_code''?action=info&type=relations[&relation=''name''][&maxres=10][&ascending=true]

  relation::
    limit response only to relations with type ''name''

  maxres::
    maximum number of results, default 10

  ascending::
    if set to true, ascending order, otherwise descending

'''Response:''' array of hashes {synset_id, synset_pos, relation_type, relation_count}

=== Last modifications ===


'''Request:''' ''servername''/''dictionary_code''?action=info&type=lastmodifications[&user=''username''][&synset=''synset_id''][&maxres=10]
 
  user::
    show only modifications by user

  synset_id::
    show only modifications for synset_id

  maxres::
    maximum number of results, default 10

'''Response:''' array of hashes {action, synset_id, time, user, version}

=== Editation statistics ===


'''Request:''' ''servername''/''dictionary_code''?action=info&type=edit[&user=''username''][&synset=''synset_id''][&month=''month'']


  user::
    show only modifications by user

  synset_id::
    show only modifications for synset_id

  month::
    statistics for given month, default previous month, format YYYY-MM

'''Response:''' array of hashes {user, synset_id, month, action_count}

=== Journal info ===
'''Request:''' ''servername''/''dictionary_code''?action=info&type=journal[&user=''username''][&synset=''synset_id''][&datefrom=''date_from''][&date_to=''date_to''][&maxres=10]


  user::
    show only modifications by user

  synset_id::
    show only modifications for synset_id

  maxres::
    maximum number of results, default 10

  date_from, date_to::
    limit information from/to given date, format YYYY-MM-DD

'''Response:''' array of hashes {action, synset_id, time, username, version}