Revision: 9336
http://languagetool.svn.sourceforge.net/languagetool/?rev=9336&view=rev
Author: dnaber
Date: 2013-02-08 23:14:49 +0000 (Fri, 08 Feb 2013)
Log Message:
-----------
document our HTTP API
Modified Paths:
--------------
trunk/website/include/header.php
trunk/website/www/http-api/index.php
Added Paths:
-----------
trunk/website/www/http-server/
trunk/website/www/http-server/index.php
Modified: trunk/website/include/header.php
===================================================================
--- trunk/website/include/header.php 2013-02-08 23:01:17 UTC (rev 9335)
+++ trunk/website/include/header.php 2013-02-08 23:14:49 UTC (rev 9336)
@@ -251,6 +251,17 @@
}
?>
<?php
+ if ($sub_page == "http-server") {
+ ?>
+ <div class="submenuitem activeMenuitem">HTTP Server</div>
+ <?php
+ } else {
+ ?>
+ <div class="submenuitem"><a href="<?php print $rootUrl
?>/http-server/">HTTP Server</a></div>
+ <?php
+ }
+ ?>
+ <?php
if ($page == "developer-links") {
?>
<div class="submenuitem activeMenuitem">Links</div>
Modified: trunk/website/www/http-api/index.php
===================================================================
--- trunk/website/www/http-api/index.php 2013-02-08 23:01:17 UTC (rev
9335)
+++ trunk/website/www/http-api/index.php 2013-02-08 23:14:49 UTC (rev
9336)
@@ -3,126 +3,43 @@
$sub_page = "http-api";
$title = "LanguageTool";
$title2 = "HTTP API";
-$lastmod = "2012-11-29 19:20:00 CET";
+$lastmod = "2013-02-08 23:20:00 CET";
include("../../include/header.php");
-include('../../include/geshi/geshi.php');
?>
-<h2 class="firstpara">Using LanguageTool from Other Applications</h2>
+<h2 class="firstpara">Public REST API</h2>
- <p>LanguageTool comes with its own embedded HTTP server so you can send a
text
- to LanguageTool via HTTP and get the detected errors back as XML. This
embedded server can be started in two ways:</p>
+<p>We offer an HTTPS REST service that anybody can use to check text with
LanguageTool.
+When using it, please keep the following rules in mind:</p>
- <ul>
- <li>Start the stand-alone application and configure it (<em>File ->
Options...</em>) to listen on a port that
- is not used yet (the default port, 8081, should often be okay). This
way LanguageTool will also be available
- in server mode until you stop it.
- </li>
- <li>
- <p>Start LanguageTool on the command line using this command:</p>
+<ul>
+ <li>Please do not send automated requests. For that, set up
+ <?=show_link("your own instance of LanguageTool", "../http-server/") ?>,
which is very easy.</li>
+ <li>Access is currently limited to 20 requests per IP per minute.</li>
+ <li>The maximum text size is limited (currently to 50KB).</li>
+ <li>Only HTTPS is supported, not HTTP.</li>
+ <li>This is a free service, thus there are no guarantees about performance
or availability.</li>
+ <li>The LanguageTool version installed may be the latest official release or
some snapshot. We will simply
+ deploy new versions, thus the behavior might change without any
warning.</li>
+ <li>We promise that we only log meta data of your requests (date/time, text
length, language), not the actual text.</li>
+</ul>
- <tt>java -cp LanguageTool.jar
org.languagetool.server.HTTPServer</tt>
+<h2>URL</h2>
- <p>You can use the <tt>--port</tt> or <tt>-p</tt> option to specify
the port number. If
- no port number is specified, the default (8081) is used. For security
reasons, the server will
- not be accessible from other hosts. If you want to run a server for
remote users you will
- need the <tt>--public</tt> option (not much tested and thus
deprecated) or write a small Java program
- that creates an instance of
- <tt><a
href="http://www.languagetool.org/development/api/index.html?org/languagetool/server/HTTPServer.html";>org.languagetool.server.HTTPServer</a></tt>.
- </li>
- </ul>
+<p>The service is running at languagetool.org port 8081, so you can test it
like this:</p>
- <p>You can test the server by calling this URL in your browser:</p>
+<code><a
href="https://languagetool.org:8081/?language=en-US&text=my+texd";>https://languagetool.org:8081/?language=en-US&text=my+texd</a></code>
- <tt>http://localhost:8081/?language=en&text=my+text</tt><br />
+<p>If you're not just testing you should use POST to transfer your data. You
+can test it like this, using <?=show_link("curl", "http://curl.haxx.se/";)
?>:</p>
- <p>If you're not just testing you should use HTTP POST to transfer your
data. You
- can test it like this:</p>
+<tt>curl --data "language=en-US&text=my texd"
https://languagetool.org:8081</tt>
- <tt>curl --data "language=en-US&text=a simple test"
http://localhost:8081</tt>
+<p>Please see <?=show_link("HTTP server", "../http-server/") ?> for information
+about the parameters you can supply.</p>
- <p>The <tt>language</tt> parameter must specify the language code
- of the text to be checked, e.g. <tt>en</tt> (English) or <tt>en-US</tt>
(American English).
- If the language has country variants and you want spell checking, you need
to use the language code that
- includes the variant (e.g. <tt>en-US</tt> instead of just <tt>en</tt>).</p>
+<br/><br/><br/><br/><br/><br/><br/><br/>
- <p>You can also specify <tt>motherTongue</tt>
- parameter to specify your mother tongue (for false friend checks). The
<tt>text</tt> parameter is the
- text itself. If you want to test bilingual text (containing
- source and translation), simply specify also the <tt>srctext</tt>
parameter. This way
- <a
href="http://languagetool.wikidot.com/checking-translations-bilingual-texts";>bitext
mode</a> will be activated automatically.</p>
-
- <p>The server may be configured to enable or disable some rules by
adding <tt>enabled</tt> and
- <tt>disabled</tt> as parameters and listing rule identifiers delimited
with commas, for example:</p>
-
-
<tt>http://localhost:8081/?language=en&disabled=STRANGE_RULE,ANOTHER_RULE&text=my+text</tt><br
/>
-
- <p>In this example, two rules will be disabled: <tt>STRANGE_RULE</tt>
and <tt>ANOTHER_RULE</tt>. Note that there
- should be no space after the comma.</p>
-
- <p>Note that for a server started from a GUI, a user may configure it
in the configuration dialog box to disable
- some unwanted rules. This may be beneficial if the calling program does
not allow configuration of the call to the
- LanguageTool server, and the user wants to enable or disable some
checks. However, if the program does disable or
- enable any rules, then the configuration set by the user will be
silently ignored.</p>
-
- <p>For the input "this is a test" the LanguageTool server will reply with
- an XML response like this:</p>
-
-<div class="xmlrule" style="margin-top:5px"><?php hl('<?xml version="1.0"
encoding="UTF-8"?>
-<matches software="LanguageTool" version="1.9" buildDate="2012-09-29">
-<error fromy="0" fromx="0" toy="0" tox="5"
- ruleId="UPPERCASE_SENTENCE_START"
- msg="This sentence does not start with an uppercase letter"
- replacements="This" context="this is a test."
- contextoffset="0" offset="0"
- errorlength="4" category="Capitalization"/>
-</matches>'); ?>
-</div>
-
- <p>Some rules contain a link to a webpage. The link
- will be available as the contents of the <tt>url</tt> attribute of the
<tt>error</tt> element.</p>
-
- <p>Here's <?=show_link("a DTD with short descriptions of the elements",
"https://languagetool.svn.sourceforge.net/svnroot/languagetool/trunk/languagetool/languagetool-core/src/main/resources/org/languagetool/resource/api-output.dtd";,
0) ?>.</p>
-
- <p>You can call <tt>http://localhost:8081/Languages</tt> to get a list of
all languages available.</p>
-
-<h3>Using SSL</h3>
-
-<p>Starting with version 2.0, LanguageTool offers an embedded HTTPS server. It
works just like the HTTP server
-described above, but it only supports <tt>https</tt>. It can be started like
this:</p>
-
-<tt>java -cp LanguageTool.jar org.languagetool.server.HTTPSServer --config
server.properties</tt>
-
-<p><tt>server.properties</tt> is a Java properties file like this:</p>
-
-<pre class="command">
-# Path to Java key store:
-keystore = keystore.jks
-# Password for the Java key store:
-password = my-password
-# Maximum text length. Optional - longer texts will not be checked:
-maxTextLength = 50000
-</pre>
-
-<p>To run the server you need your own SSL certificate, just like when you
protect your
-webserver using SSL. Assuming you have the required files in PEM format, which
looks like this:</p>
-
-<pre>
------BEGIN RSA PRIVATE KEY-----
-(lots of random characters here)
------END RSA PRIVATE KEY-----
-</pre>
-
-<p>You can convert this format to the Java keystore format which LanguageTool
needs with openssl and with
-the <tt>keytool</tt> command that comes with Java:</p>
-
-<pre class="command">
-cat key crt ca.crt >server.pem
-openssl pkcs12 -export -out server.p12 -in server.pem
-keytool -importkeystore -srckeystore server.p12
- -srcstoretype pkcs12 -destkeystore keystore.jks -deststoretype jks
-</pre>
-
<?php
include("../../include/footer.php");
?>
Copied: trunk/website/www/http-server/index.php (from rev 9305,
trunk/website/www/http-api/index.php)
===================================================================
--- trunk/website/www/http-server/index.php (rev 0)
+++ trunk/website/www/http-server/index.php 2013-02-08 23:14:49 UTC (rev
9336)
@@ -0,0 +1,128 @@
+<?php
+$page = "development";
+$sub_page = "http-server";
+$title = "LanguageTool";
+$title2 = "HTTP Server";
+$lastmod = "2013-02-08 23:20:00 CET";
+include("../../include/header.php");
+include('../../include/geshi/geshi.php');
+?>
+
+<h2 class="firstpara">Accessing LanguageTool via HTTP</h2>
+
+ <p>LanguageTool comes with its own embedded HTTP server so you can send a
text
+ to LanguageTool via HTTP and get the detected errors back as XML. This
embedded server can be started in two ways:</p>
+
+ <ul>
+ <li>Start the stand-alone application and configure it (<em>File ->
Options...</em>) to listen on a port that
+ is not used yet (the default port, 8081, should often be okay). This
way LanguageTool will also be available
+ in server mode until you stop it.
+ </li>
+ <li>
+ <p>Start LanguageTool on the command line using this command:</p>
+
+ <tt>java -cp LanguageTool.jar
org.languagetool.server.HTTPServer</tt>
+
+ <p>You can use the <tt>--port</tt> or <tt>-p</tt> option to specify
the port number. If
+ no port number is specified, the default (8081) is used. For security
reasons, the server will
+ not be accessible from other hosts. If you want to run a server for
remote users you will
+ need to use the <tt>--public</tt> option (not much tested yet) or
write a small Java program
+ that creates an instance of
+ <tt><a
href="http://www.languagetool.org/development/api/index.html?org/languagetool/server/HTTPServer.html";>org.languagetool.server.HTTPServer</a></tt>.
+ </li>
+ </ul>
+
+ <p>You can test the server by calling this URL in your browser:</p>
+
+ <tt>http://localhost:8081/?language=en&text=my+text</tt><br />
+
+ <p>If you're not just testing you should use HTTP POST to transfer your
data. You
+ can test it like this, using <?=show_link("curl", "http://curl.haxx.se/";)
?>:</p>
+
+ <tt>curl --data "language=en-US&text=a simple test"
http://localhost:8081</tt>
+
+ <p>The <tt>language</tt> parameter must specify the language code
+ of the text to be checked, e.g. <tt>en</tt> (English) or <tt>en-US</tt>
(American English).
+ If the language has country variants and you want spell checking, you need
to use the language code that
+ includes the variant (e.g. <tt>en-US</tt> instead of just <tt>en</tt>).</p>
+
+ <p>You can also specify the <tt>motherTongue</tt>
+ parameter to specify your mother tongue for false friend checks. The
<tt>text</tt> parameter is the
+ text itself. If you want to test bilingual text (containing
+ source and translation), simply specify also the <tt>srctext</tt>
parameter. This way
+ <a
href="http://wiki.languagetool.org/checking-translations-bilingual-texts";>bitext
mode</a> will be activated automatically.</p>
+
+ <p>The server may be configured to enable or disable some rules by
adding <tt>enabled</tt> and
+ <tt>disabled</tt> as parameters and listing rule identifiers delimited
with commas, for example:</p>
+
+
<tt>http://localhost:8081/?language=en&disabled=STRANGE_RULE,ANOTHER_RULE&text=my+text</tt><br
/>
+
+ <p>In this example, two rules will be disabled: <tt>STRANGE_RULE</tt>
and <tt>ANOTHER_RULE</tt>. Note that there
+ should be no space after the comma.</p>
+
+ <p>Note that for a server started from a GUI, a user may configure it
in the configuration dialog box to disable
+ some unwanted rules. This may be beneficial if the calling program does
not allow configuration of the call to the
+ LanguageTool server, and the user wants to enable or disable some
checks. However, if the program does disable or
+ enable any rules, then the configuration set by the user will be
silently ignored.</p>
+
+ <p>For the input "this is a test" the LanguageTool server will reply with
+ an XML response like this:</p>
+
+<div class="xmlrule" style="margin-top:5px"><?php hl('<?xml version="1.0"
encoding="UTF-8"?>
+<matches software="LanguageTool" version="1.9" buildDate="2012-09-29">
+<error fromy="0" fromx="0" toy="0" tox="5"
+ ruleId="UPPERCASE_SENTENCE_START"
+ msg="This sentence does not start with an uppercase letter"
+ replacements="This" context="this is a test."
+ contextoffset="0" offset="0"
+ errorlength="4" category="Capitalization"/>
+</matches>'); ?>
+</div>
+
+ <p>Some rules contain a link to a webpage. The link
+ will be available as the contents of the <tt>url</tt> attribute of the
<tt>error</tt> element.</p>
+
+ <p>Here's <?=show_link("a DTD with short descriptions of the elements",
"https://languagetool.svn.sourceforge.net/svnroot/languagetool/trunk/languagetool/languagetool-core/src/main/resources/org/languagetool/resource/api-output.dtd";,
0) ?>.</p>
+
+ <p>You can call <tt>http://localhost:8081/Languages</tt> to get a list of
all languages available.</p>
+
+<h3>Using SSL</h3>
+
+<p>Starting with version 2.0, LanguageTool offers an embedded HTTPS server. It
works just like the HTTP server
+described above, but it only supports <tt>https</tt>. It can be started like
this:</p>
+
+<tt>java -cp LanguageTool.jar org.languagetool.server.HTTPSServer --config
server.properties</tt>
+
+<p><tt>server.properties</tt> is a Java properties file like this:</p>
+
+<pre class="command">
+# Path to Java key store:
+keystore = keystore.jks
+# Password for the Java key store:
+password = my-password
+# Maximum text length. Optional - longer texts will not be checked:
+maxTextLength = 50000
+</pre>
+
+<p>To run the server you need your own SSL certificate, just like when you
protect your
+webserver using SSL. Assuming you have the required files in PEM format, which
looks like this:</p>
+
+<pre>
+-----BEGIN RSA PRIVATE KEY-----
+(lots of random characters here)
+-----END RSA PRIVATE KEY-----
+</pre>
+
+<p>You can convert this format to the Java keystore format which LanguageTool
needs with openssl and with
+the <tt>keytool</tt> command that comes with Java:</p>
+
+<pre class="command">
+cat key crt ca.crt >server.pem
+openssl pkcs12 -export -out server.p12 -in server.pem
+keytool -importkeystore -srckeystore server.p12
+ -srcstoretype pkcs12 -destkeystore keystore.jks -deststoretype jks
+</pre>
+
+<?php
+include("../../include/footer.php");
+?>
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
Free Next-Gen Firewall Hardware Offer
Buy your Sophos next-gen firewall before the end March 2013
and get the hardware for free! Learn more.
http://p.sf.net/sfu/sophos-d2d-feb
_______________________________________________
Languagetool-commits mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/languagetool-commits
