APE Webservice

Introduction

This document describes the APE Webservice (version 6.6 and higher). The service translates an ACE text into a Discourse Representation Structure (DRS) and other logical forms. It can be accessed over the HTTP protocol using GET or POST. The URL of the service is

http://attempto.ifi.uzh.ch/ws/ape/apews.perl

An example of a GET query is

http://attempto.ifi.uzh.ch/ws/ape/apews.perl?text=Every+man+is+a+human.&solo=drspp

which returns the pretty-printed DRS of the ACE sentence Every man is a human..

Note that the APE executable (ape.exe) supports the -httpserver flag which lets you start your own webservice. See more in the APE documentation.

The rest of this document specifies the input and the output of the service and lists some example clients.

Input

The following table lists all the parameters that can be used as input to APE. A correct query has to minimally specify the ACE text (by text or file). The c-parameters (those whose name starts with c) can be used to configure which types of outputs are produced. The solo-parameter can be used to specify a single output type. In this case, all the c-parameters are ignored.

All flags are off by default.

The value of ulexfile is a URL of the user lexicon (see the ACE lexicon specification). When used for the first time, the user lexicon is downloaded from the given URL and stored locally. The subsequent queries that use the same URL for the user lexicon do not force the lexicon to be reloaded. If the lexicon is changed, it has to be explicitly reloaded by including ulexreload=on in the query.

Output

The most important output component is the DRS. See the documentation in the DRS Report. The webservice also provides additional data about the tokenization and syntax of the input text, as well as its paraphrases (in ACE). These outputs help to understand whether the translation into the DRS is the intended one.

Additionally, the webservice can convert the DRS into other logical languages: standard representations of first-order logic, OWL/SWRL, TPTP, and RuleML.

In case the input is not a well-formed ACE text, an error message is returned. Also, if the input was successfully translated into DRS, but the DRS was not supported by the further conversion (to a paraphrase, OWL, TPTP, etc.), an error message is returned.

Solo output

In case solo is set, the APE Webservice generates just one output. This makes integration with applications which accept URLs as input easier. Each output has its corresponding Internet media type.

Note that the outputs that are denoted by 'Prolog term', 'Prolog list', etc. are serialized Prolog terms which can be read back into true terms by Prolog-based clients when using atom_to_term/3.

In case of errors or warnings, only the error/warning messages are output (in XML).

Combined output

Unless solo is set, APE outputs an XML document (content type text/xml) encoded in UTF-8 character set with a root element apeResult. This output is formally specified by an XML Schema apews_output.xsd. The children of the root element are an element duration which reports the time that APE spent on processing the ACE text (in seconds), an element messages which is used to output warning and error messages, and a subset of elements drs, drsxml, drspp, drshtml, paraphrase, paraphrase1, paraphrase2, tokens, sentences, syntax, syntaxpp, syntaxd, syntaxdpp, owlfss, owlfsspp, owlrdf, owlxml, fol, pnf, tptp, ruleml.

The output of the webservice could look like the following.

<?xml version='1.0' encoding='UTF-8'?>
<apeResult>
<duration tokenizer="0.01" parser="0.05" refres="0.0"/>
<tokens>[['Some', frogs, are, green, '.'], ['Kermit', is, a, frog, '.']]</tokens>
<drs>drs([A, B, C, D, E], [object(A, frog, countable, na, geq, 2)-1/2,
property(B, green, pos)-1/4, predicate(C, be, A, B)-1/3,
object(D, frog, countable, na, eq, 1)-2/4,
predicate(E, be, named('Kermit'), D)-2/2])</drs>
</apeResult>

Error messages

If the translation fails, APE returns an empty DRS (drs([],[])) and a list of error messages. Then an element messages is output.

<?xml version="1.0" encoding="UTF-8"?>
<apeResult>
<duration tokenizer="0.09" parser="0.2" refres="0.1"/>
<drs>drs([], [])</drs>
<tokens>[['Every', man, waits, '.'], ['He', eats, '.']]</tokens>
<messages>
    <message importance="error" type="refres" sentence="2" token="1"
        value="Unresolved anaphor: he"
	repair="Identify correct accessible antecedent."/>
</messages>
</apeResult>

An ACE text can be erroneous for several reasons:

1. the input contained a wordform that was not described in the lexicon(s),
2. the input violated the ACE syntax rules,
3. the input was syntactically correct but anaphoric references could not be resolved.

Note that the exact location of the syntax error is pinpointed.

<?xml version="1.0" encoding="UTF-8"?>

<messages>
  <message
    importance="error"
    type="sentence"
    sentence="1"
    token="4"
    value="A man runs <> very fast."
    repair="This is the first sentence that was not ACE.
            The sign <> indicates the position where parsing failed."/>

Note that sometimes errors occur after a correct DRS has been generated. E.g. the translation of ACE texts into OWL is based on the DRS, but not all DRSs are supported in this translation. In this case an error message is reported (which has a type owl).

Example clients

We have implemented some clients of the APE Webservice to demonstrate APE's interface and how it can be used in different programming languages. Feel free to extend or embed this code.

• acetext_to_drs-get.perl is a Perl client using the LWP library (available at CPAN). It can be run on any platform which has Perl and LWP installed. It is a simple client which reads a line from STDIN, sends it to the APE server and displays the resulting DRS in STDOUT.
• acetext_to_owl-post.perl is otherwise the same as the previous example, but returns OWL (XML) and uses HTTP POST to retrieve it.
• acetext_to_drs.pl is a simple Prolog client using the SWI-Prolog http- and xml-libraries.
• acetext_to_drs-with_ulex.pl is another simple Prolog client using the SWI-Prolog http- and xml-libraries. It uses APE with a small user lexicon.
• HTML client is a very simple client which runs in a web browser. It shows the resulting XML as is, i.e. without any styling or filtering. (Note that some browsers cannot display unstyled XML.)

Since all major programming languages have libraries available for sending queries over HTTP, it is probably possible to use the APE Webservice from your favorite language. If you implement an improved version of the existing clients or a new client in another programming language and want to share your work, please contact us.