From 450ed86174bee1d518c577d4b7909bb2014c002d Mon Sep 17 00:00:00 2001
From: Martijn Vermaat <martijn@vermaat.name>
Date: Wed, 30 May 2012 14:43:50 +0000
Subject: [PATCH] Documentation on HTTP/RPC+JSON webservice
git-svn-id: https://humgenprojects.lumc.nl/svn/mutalyzer/branches/rpclib-branch@544 eb6bd6ab-9ccd-42b9-aceb-e2899b4a52f1
---
mutalyzer/templates/webservdoc.html | 26 -------------------------
mutalyzer/templates/webservices.html | 29 ++++++++++++++++++++--------
mutalyzer/website.py | 19 +++++++++++-------
tests/test_website.py | 4 ++--
4 files changed, 35 insertions(+), 43 deletions(-)
delete mode 100644 mutalyzer/templates/webservdoc.html
diff --git a/mutalyzer/templates/webservdoc.html b/mutalyzer/templates/webservdoc.html
deleted file mode 100644
index 03a27cdf..00000000
--- a/mutalyzer/templates/webservdoc.html
+++ /dev/null
@@ -1,26 +0,0 @@
-<html>
- <head>
- <title></title>
- </head>
- <body>
- <div metal:define-macro="content">
- <script type="text/javascript">
- function setHeight() {
- parent.document.getElementById('docframe').height =
- document['body'].scrollHeight * 32;
- }
- </script>
- <center>
- <h3>Webservices documentation</h3>
- </center>
- <iframe
- id = "docframe"
- src = "documentation"
- width="100%"
- frameborder = "0"
- scrolling = "no"
- onload = "setHeight();">
- </iframe>
- </div>
- </body>
-</html>
diff --git a/mutalyzer/templates/webservices.html b/mutalyzer/templates/webservices.html
index f1a7463d..c9dbd304 100644
--- a/mutalyzer/templates/webservices.html
+++ b/mutalyzer/templates/webservices.html
@@ -5,14 +5,19 @@
<body>
<div metal:define-macro="content">
<center>
- <h3>Webservices page</h3>
+ <h3>Webservices</h3>
</center>
<br>
- Most Mutalyzer functionality is available trough a SOAP webservice.
+ Most Mutalyzer functionality is programmatically available trough two
+ interfaces: a SOAP webservice and a HTTP/RPC+JSON webservice.
+ <br>
+ <h3>SOAP webservice</h3>
A <a href="services/?wsdl">WSDL description</a> is available
- for easy generation of client programs in many languages.
- <h3>Example clients</h3>
- The following are some example client programs for the webservice. They
+ for easy generation of client programs in many languages. See the
+ <a href = "soap-api">annotated API</a> for detailed documentation.
+ <br>
+ <br>
+ The following are some example client programs for SOAP webservice. They
use the <a href="documentation#op.checkSyntax">checkSyntax</a> method
to determine if a variant description adheres to the <span class="helper"
title="Human Genome Variation Society standard variant nomenclature">
@@ -32,9 +37,17 @@
Here is an example that could be used for
<a href="download/textmining.py">text mining</a> on a
<a href="downloads/textmining_sample.txt">sample</a> input file.
- <h3>Documentation</h3>
- Also see the <a href = "documentation">documentation</a> page for a full
- description of the webservice.
+ <h3>HTTP/RPC+JSON webservice</h3>
+ The HTTP/RPC+JSON webservice is experimental and currently undocumented.
+ It can be called using HTTP GET requests on <code tal:content = "structure string:${location}${serviceJsonLocation}/method?param=value"></code> where <code>method</code> is the name of the method to be called and method parameters are expected as <code>param=value</code> query string parameters. Responses are JSON-encoded.
+ <br>
+ <br>
+ Example: <a tal:attributes="href string:${location}${serviceJsonLocation}/checkSyntax?variant=AB026906.1:c.274del" tal:content="structure string:checkSyntax?variant=AB026906.1:c.274del"></a>
+ <br>
+ <br>
+ For now, you can work from this example using the above mentioned
+ <a href="soap-api">annotated SOAP API</a>, since the HTTP/RPC+JSON
+ webservice mirrors the functionality of the SOAP webservice.
</div>
</body>
</html>
diff --git a/mutalyzer/website.py b/mutalyzer/website.py
index da8c89b1..15f5dcf4 100644
--- a/mutalyzer/website.py
+++ b/mutalyzer/website.py
@@ -3,7 +3,8 @@ General Mutalyzer website interface.
"""
-WEBSERVICE_LOCATION = '/services'
+SERVICE_SOAP_LOCATION = '/services'
+SERVICE_JSON_LOCATION = '/json'
WSDL_VIEWER = 'templates/wsdl-viewer.xsl'
GENOME_BROWSER_URL = 'http://genome.ucsc.edu/cgi-bin/hgTracks?db=hg19&position={chromosome}:{start}-{stop}&hgt.customText={bed_file}'
@@ -60,7 +61,6 @@ urls = (
'/(disclaimer)', 'Static',
'/(nameGenerator)', 'Static',
'/(webservices)', 'Static',
- '/(webservdoc)', 'Static',
'/checkForward', 'CheckForward',
'/check', 'Check',
'/bed', 'Bed',
@@ -72,7 +72,7 @@ urls = (
'/batch([a-zA-Z]+)?', 'BatchChecker',
'/progress', 'BatchProgress',
'/Results_(\d+)\.txt', 'BatchResult',
- '/documentation', 'Documentation',
+ '/soap-api', 'SoapApi',
'/Variant_info', 'VariantInfo',
'/getGS', 'GetGS',
'/download/([a-zA-Z-]+\.(?:py|cs|php|rb))', 'Download',
@@ -135,6 +135,8 @@ class render_tal:
context.addGlobal('interactive', not standalone)
+ context.addGlobal('location', web.ctx.homedomain + web.ctx.homepath)
+
for name, value in self.globals.items():
context.addGlobal(name, value)
@@ -178,7 +180,10 @@ render = render_tal(os.path.join(mutalyzer.package_root(), 'templates'),
'releaseDate' : mutalyzer.__date__,
'release' : mutalyzer.RELEASE,
'copyrightYears' : mutalyzer.COPYRIGHT_YEARS,
- 'contactEmail' : config.get('email')})
+ 'contactEmail' : config.get('email'),
+ 'serviceSoapLocation' : SERVICE_SOAP_LOCATION,
+ 'serviceJsonLocation' : SERVICE_JSON_LOCATION
+})
# web.py application
app = web.application(urls, globals(), autoreload = False)
@@ -1416,7 +1421,7 @@ class Uploader:
#Uploader
-class Documentation:
+class SoapApi:
"""
SOAP webservice documentation.
"""
@@ -1443,7 +1448,7 @@ class Documentation:
@todo: Use configuration value for .xsl location.
@todo: Cache this transformation.
"""
- url = web.ctx.homedomain + web.ctx.homepath + WEBSERVICE_LOCATION
+ url = web.ctx.homedomain + web.ctx.homepath + SERVICE_SOAP_LOCATION
wsdl = Wsdl11(soap.application.interface)
wsdl.build_interface_document(url)
wsdl_handle = StringIO(wsdl.get_interface_document())
@@ -1456,7 +1461,7 @@ class Documentation:
web.header('Content-Type', 'text/html')
return str(transform(wsdl_doc))
#GET
-#Documentation
+#SoapApi
class Static:
diff --git a/tests/test_website.py b/tests/test_website.py
index 898074d0..7589230c 100644
--- a/tests/test_website.py
+++ b/tests/test_website.py
@@ -630,11 +630,11 @@ facilisi."""
assert_equal(r.content_type, 'text/plain')
r.mustcontain('NM_003002.1:c.3_4insG')
- def test_soap_documentation(self):
+ def test_annotated_soap_api(self):
"""
Test the SOAP documentation generated from the WSDL.
"""
- r = self.app.get('/documentation')
+ r = self.app.get('/soap-api')
assert_equal(r.content_type, 'text/html')
r.mustcontain('Web Service: Mutalyzer')
--
GitLab