Skip to content
This repository has been archived by the owner on Jan 9, 2023. It is now read-only.

The Web Service

Jump to bottom
Anonymous edited this page Sep 10, 2015 · 25 revisions

The web service allow you to access the myEquivalents functionality via the HTTP protocol and the REST approach. This allows external applications to use myEquivalents through a standardised web layer, without the need for direct access to back ends like the relational database, which makes things safer.

The web service can be used by a client application sending in HTTP/REST requests, either directly or by means of some web service library. If your client code is based on Java, we recommend that you use this with the web service client counter-part. This makes things easier and less error-prone. Moreover, if you use the myEquivalents managers abstractions, your client will be portable, i.e., independent on the particular myEquivalents access mean.

Other myEquivalents access interfaces, such as the programmatic access or the command line, can use the web service to reach a myEquivalents instance.

This is also true for the server side of the web service. By default, the web service is configured to use the relational database. As explained elsewhere, you can set which database that connects to by changing the Spring meta-data file myeq-manager-config.xml, which has to be put in a proper location on your Java application server (see below).

The next sections are about the deployment and installation of web service's server side. You find the documentation about the client here.

##Preparing the web service A very simple way to run the server component for the web service is to run it via the Maven Jetty plug-in. Do that by:

  • go to myequivalents root source folder and issue 'mvn -P... install', as explained above (Jetty will work with the in-memory HSQL database if you don't use -P).
  • cd myequivalents-web and issue 'mvn -P... jetty:run'

If you don't notice any error message in the output of such command, you should be able to check that the service is up and running by means of any web browser. For instance, a URL that should work is this, which gets some test data stored when you trigger the Jetty plug-in (the database is untouched when you deploy the .war file, unless you pass uk.ac.ebi.fg.myequivalents.test_flag=true to the JVM). The browser should show the same XML reported in the examples above.

You can keep the Maven/Jetty instance running and use it to test the web service client (see below).

##Setting up into an application server, Tomcat

  • Build the war, issuing 'mvn -P... package' from either the top level or the myequivalents-web module. See here for details about Maven profiles.
  • from myequivalents-web, run ./deploy2tomcat.sh <TOMCAT_HOME> [app-context-path] [app-config-dir]. This assumes you're under some Unix system or using an equivalent environment (e.g., Cygnus). The script will copy the generated .war file and the myeq-manager-config.xml that corresponds to the database profile selected with -P. The script asks if you want to replace existing files.
  • This means that you can change database parameters on the Tomcat home, even after installation, by changing the myeq-manager-config.xml file.
  • If you want test-data loaded into the myequivalents database, type (under Bash shell):
$ export JAVA_OPTS='-Duk.ac.ebi.fg.myequivalents.test_flag=true'

This will cause the web service application to load some test data when it starts.

  • Start or run the server, e.g. 'cd $TOMCAT_HOME/bin; ./catalina.sh run'
  • You should be able to see some mappings via an URL like this
  • You can make further tests by using some myEquivalents access interface, for instance the command line set to use the web service client.

You can change the web application root '/myequivalents' by changing the name of the .war file mentioned above. Please note, that there is no way you can detach the name of a .war file from the application id that Tomcat maps the file to. Instead, you can name the file like examples#myeq, to get it mapped to /examples/myeq. This is done automatically by the deployment script above (using slashes in app-context parameter).

You can deploy multiple instances of the web application web service on the same Tomcat server, each using a different configuration/back end, by using different values for the app-context-path and app-config-dir parameters above. Of course the clients will need to be configured accordingly (i.e., set a proper web service's root URL).

###Setting up and enforcing HTTPS connections Here you find an example of how to set up Tomcat to support encrypted SSL-based connections and how to enforce them. This is important if your web service clients are connecting through arbitrary networks and not ones that you can trust, such as your LAN. HTTPS connections will encrypt parameters like myEquivalents passwords (which are always part of the web service request body, i.e., all authenticated requests are made via POST HTTP invocations).

##Setting up into an application server, non Tomcat Although we officially support Jetty and Tomcat only, the generated web application should work with any standard Java application server. What you need to do is:

  • Copy the .war into a proper destination
  • Create a configuration directory named something like myequivalents-conf into an approriate location
  • After having built the myequivalents-web module, as explained above, copy target/classes/myeq-manager-config.xml into the configuration directory.
  • Copy context.xml into a location and name approriate for your application server. For instance, into <server_home>/conf/myequivalents.xml. The server should be able to associate this context file to the binary file myequivalents.war.
  • Modify the copy of context.xml that you placed into the server, in order to set the above mentioned configuration directory via the 'myequivalents.config-location' parameter.
  • If you want test data, set the Java option uk.ac.ebi.fg.myequivalents.test_flag=true (in whatever way your server's documentation tell to do so).
  • Restart the server (or deploy myequivalents.war).

Setting the configuration location in the context.xml allows you to have multiple instances of the myEquivalents service on the same web application server.

##HTTP-Forward Requests '/go-to-target' is a request type that is only available from the web service (the other interfaces, such as the programmatic access or the web service client, have a similar method). This gets the identifier of an entity plus the name of a target service and, in most cases, it redirects the client (HTTP/301, Moved Permanently) to the URI that corresponds to the counter-part of the input entity on the target service. In other words, you can put a link like this directly into a web page in your service (service8 in this example), to get the user redirected to the correspondent entity on another service of interest (service7 in the example).

If the input entity is not mapped anywhere in the target service HTTP/404 (Not Found) is returned. While of the times you will have a single result for a given target, you cannot completely rule out the case where an entity is mapped to multiple entities on the same target service (unless, of course, you are very sure of what you have mapped on myEquivalents). When that is the case, the /go-to-target request returns some XML as result, which is almost identical to the XML returned by the (line-command mapping get)[wiki/The-Command-Line-Access] and contains the multiple results found on the targed service for the input entity. Such XML is equipped with the URL of an XSL file, so the browser can render it as a proper web page and show the final result. We provide a simple default XSL for that, you can pass your own XSL by specifing its URL with the xsl parameter in the /go-to-target request. For instance the URL:

http://localhost:8080/ws/mapping/go-to-target?entity=test.testweb.service7:acc1&service=test.testweb.service6&xsl=/xsl/myeq/go-to-target.xsl

would point to an althernative XSL file located at localhost (i.e., the same domain where myEquivalents is). Typically such stylesheet will take the XML returned by the /go-to-target request for the case of multiple results and it will present such results in a page that has the same layout and formatting used for all the pages at ourserver.com. As you might already have guessed, the default XSL is a good place to start to build such a custom XSL.

###WARNING: the xsl parameter has a same-domain restriction When using the xsl parameter above, you cannot point at a document that is located under a domain different than the one where the myEquivalents web service is. More precisely, if you do that, due to security issues, almost certainly the user browsers will refuse to use such an XSL to render the final landing page. The xsl parameter is a feature designed for those who have access to the same server side that the organisation running myEquivalents has access to. If instead you are using an instance of myEquivalents web service that is outside your domain, you still have other options:

  • Ask the administrators of the myEquivalents web server you are using to upload your own xsl file. We plan to support this option in future, within a more general mechanism for user management and accesso control.
  • Write your own forwarding page, using the web service client. We plan to develop examples about that (in JSP or Javascript/AJAX).
  • Deploy your own myEquivalents web service instance. This can be backed by either your own database, or a third-party database, or it could be a proxy to another server (i.e. backed by the web service client).
  • Ask your user to relax their browser's security restrictions. No, that is not really an option. We mention it just to make it clear that it is totally unrealistic, due to serious security issues, not to mention irresponsible toward your users.
Clone this wiki locally