Introduction

The EMBRACE registry is a collection of life-science web services originating from the EMBRACE Network of Excellence. As a potential user of these, you can search the registry for services that match your needs, and find example client software to help you use them in your own programs or workflows. The registry periodically monitors the status and behaviour of the registered services, collating and logging this information so that you can see how reliable services are, and whether they are currently functioning as the service providers expect them to.

How The Registry Works

Authors of web services submit a description of their service to the registry, along with optional functional and conformance tests. Functional tests are simple client scripts that connect to a web service, ask it to perform some operation, and then test to see whether the results are as expected. These can be written in a number of popular languages including Python, Perl and Java. Conformance tests examine the service in detail to see whether it uses standard ‘best practice’ techniques.

Service Status Icons

Each service in the registry is given a service status that gives an overall indication of the health of a particular service. Broadly speaking the statuses can be interpreted like this:

Unknown. All services start of with the unknown status. This means that the registry knows about the existence of a service, but hasn’t yet been able to test whether that services works.

Ok. A green ‘Ok’ status means that as far as the registry is concerned, the service is behaving correctly.

Warning. The amber ‘Warning’ status means that the registry has detected something unusual about a service’s status; it is probably still functioning in some form, but you should be cautious about relying on any results you get back from the service whilst it is in this state.

Error. The red ‘Error’ status means that the registry has not been able to communicate with the service recently.

Because of the nature of distributed services, the status icons represented by the registry can’t guarantee to be completely up to the minute and definitive. The interpretation of the statuses just described is a good day-to-day indication of what’s going on, but to completely understand what the statuses mean, and what implications this may have for your own client programs, you should read the full status descriptions.

Understanding Service Statuses

To fully understand what status icons mean, you’ll need to be familiar with the way the registry tests services. The registry maintains a set of tests for each service it monitors, and runs these periodically, assembling the results to give an overall status indication. Each test can return ‘Passed’, ‘Failed’, or ‘Warning’. If all of a service’s tests passed in the most recent run, then a service is given the ‘Ok’ status; if they all fail, it is given the ‘Error’ status; if the most recent run gives a mixture of passes and fails, or any one test returns a ‘Warning’, then the the service itself is marked as being in a ‘Warning’ state. You can examine the most recent test runs (and all the historical ones too, if you really want) from a service’s entry page, and this should give you a clearer view of how a service is currently behaving.

Test results (which a distinct from Service Statuses) can be one of the following:

Passed : the registry was able to execute this test, and the results were exactly as the authors expected

Failed : either the registry couldn’t execute this test for some reason, or the test couldn’t communicate with the service.

Warning : the test could be executed, and it returned some results, but there was something untoward about these.

The tests associated with a particular service are provided by the service’s authors, and what exactly gets tested is entirely at their discretion. The nature of these tests depends very much on the what a service actually does, so to fully interpret the results, you’d need to understand the service and look at what a test does in detail. For example, if a service provides programmatic access to an online database, and that database guarantees that a record is never modified once its published, then the test may request a particular record, and check various fields to see whether they are as expected, since any variation from this would mean that something bad has happened to the source database. For other services which have a stochastic element to them, tests may have to be more forgiving in terms of what they examine since results might reasonably fluctuate from invocation to invocation. Generally speaking though, you can simply rely on the fact that authors will typically submit sensible tests to do sensible things … so for the main you can take these results at face value.

With all of this in mind, here’s a more detailed description of what a service’s status means:

Unknown : This registry knows about the existence of this service, but hasn’t been able to test it. Either it’s very recently been submitted, and the tests are yet to be run, or the authors haven’t provided any tests at all.

Ok : The last time a batch of tests were executed for this service, they all passed. It’s possible that something bad has happened since these tests were run. It’s also possible that the tests that the authors provided weren’t rigorous enough to detect a problem that you are now encountering with your code. But on the whole, you can be fairly confident that things are working well. If you are having problems with this service,
download one of the client test scripts from the service’s page and try this out.

Warning : The last the service was tested, something wasn’t right. It could be that one or more tests failed (in which case you may want to see whether that test is something you care about – it could be completely unrelated to the function you need); it could be that one or more tests returned unexpected results. In any case you should proceed with some caution if your program uses this service, since something that the authors thought was important to the integrity of the service is no longer working properly.

Error : When this service was last tested, none of the tests worked. Typically this will mean that the service is unavailable, possibly due to maintainance, or in some cases because something more catastrophic has happened such as a hardware failure at the server end. Even if your client code can somehow connect to this service, you really shouldn’t trust anything it does.

Of course, since the registry only communicates with services periodically, the actual status of the service may have changed since the last test.

Information For Service Providers

In order to add your own services to the registry, you will need to sign up for an account. This will allow you to add and modify services and tests.

What are tests?
Functional test serve two purposes within the EMBRACE registry. First, they allow the registry to monitor your service and provide reasonably up-to-date information to current and potential users about its current status, and its reliability over a long period of time. Second, they act as simple tutorials for potential users on how to use your service, since the source code for the tests is made available for all to see. You can choose whether to put documentation for the service and its tests on the registry, or simply link to your existing information.

Submitting a test
Writing a suitable test script is straightforward. The minimum that’s required is a single file which can be executed as though it were typed at a command line, and which will run to completion with no command line parameters, and without any user interaction. You will need to use the ‘#!’ notation on the first line of your file to tell the registry which language interpreter to use. The script should connect to your service, execute a function, and examine the results to check that they are ‘sensible’ (where ‘sensible’ is entirely dependent on what your service does!). The script then exits with a return value of 0 for ‘Ok’, ‘1’ for ‘Error’ and anything else for ‘Warning’. Your script can write comments to standard-out and standard-error, and these are simply captured and stored along with the log entry for the script’s execution – the server doesn’t try to interpret these in any way at all. Your script will be executed by a test harness, and runs in a virtual machine isolated from the rest of the registry. Scripts are only allowed to make outgoing connections to the rest of the world on specific ports, and have no write access to filestore of any kind. If a script fails, aborts, or crashes in any way, the test harness interprets this as ‘Error’, and writes a log entry for you.

The registry’s virtual server is configured with the following scripting and programming environments:

• Python, with ZSI and SOAPy
• Perl, with XML::Compile and SOAP::Lite
• Java, with Axis 1.4

If you need a different environment setting up, please mail the registry maintainers.

To submit your test to the registry, you will need to upload a zipped version of your script, and tell the registry what the name of the executable file is.

You can include any number of auxiliary files and directories in your test, as long as they are accessible via a single command and without command line parameters. So if your test requires additional modules or classes etc., simply include them in the zip file that you upload, in whatever file structure allows the command to run from the command line. Generally speaking though, the simpler the better; keep in mind that your test script and its associated files also act as a tutorial for new users.

Testing multiple functions

If your service has more than one function, you can choose whether to test these all in one script, or in lots of individual scripts; it’s entirely up to you. All you have to bear in mind is that if you’re testing lots of functions in one go, you can still only return ‘Passed’, ‘Failed’ or ‘Warning’ from your script, and this will be reflected in the overall status of your service. If you think that some functions may be less reliable than others, you may want to consider separating tests out in to individual scripts (this means that a failure of one test will change your service status to ‘Warning’ rather than ‘Error’). Also remember that a long script that tests many functions may be more daunting for a potential user.

Scripts in multiple programming languages

You can of course test the same function in your service from multiple programming languages; in fact we strongly encourage you to so since it provides another level of usability and robustness for your users, and allows you to detect quirks of the various libraries that may otherwise go undetected.

Example test clients

This sample client uses invokes the SMART web service to predict possible catalytic inactivity on a protein sequence. Its input is a sequence of amino acids and a UniProt ID, and its output is a list of regions or features on that sequence. Because SMART should return deterministic results for a particular input sequence, we can afford to check that these are exactly what we expect, at least for a small sample of sequences (in this case, just one!). We’ll assume here that if the values are correct for our sample, they are going to be correct for the whole database.

#!/usr/bin/python
# the first line of the script must tell us which language interpreter to use,
# in this case its python


# import the modules we need for this test; SOAPpy is included on the server
# by default, and we'll need the 'sys' module in order to be able to use
# exit to return a value from this script
from SOAPpy import WSDL
from sys import exit

# set up the input values we need for this service...
# an amino acid sequence
seq_str =  'MANLGCWMLVLFVATWSDLGLCKKRPKPGGWNTGGSRYPGQGSPGGNRYPPQGGGGWG' \
           + 'QPHGGGWGQPHGGGWGQPHGGGWGQPHGGGWGQGGGTHSQWNKPSKPKTNMKHMAGAA' \
           + 'AAGAVVGGLGGYMLGSAMSRPIIHFGSDYEDRYYRENMHRYPNQVYYRPMDEYSNQNN' \
           + 'FVHDCVNITIKQHTVTTTTKGENFTETDVKMMERVVEQMCITQYERESQAYYQRGSSM' \
           + 'VLFSSPPVILLISFLIFLIVG'
# and the corresponding UniProt ID
ID= 'P04156'

# we'll include the whole main body in a try:except clause so that if something
# unexpected happens, we can return a sensible error value

try:
    # Get web service proxy
    proxy = WSDL.Proxy('http://smart.embl-heidelberg.de/webservice/SMART_webservice.wsdl')
    
    # Execute the SMART service
    features = proxy.doSMART(protein_sequence=seq_str, protein_ID=ID)
    
    # Get the features that are returned
    feature_list = features._getItemAsList('feature')
    
    # Assume that everything will work, so start with a returnvalue of 0 / Ok
    returnvalue = 0
    
    # we're expecting exactly two features for our input sequence, so test this 
    # first
    if len(feature_list) != 2:
        # write a comment to stdout, and return a value of 2. This will be interpreted as
        # a 'warning' status
        print "SMART returned the wrong number of features for this sequence"
        returnvalue= 2
    else:
        # we got exactly two features, so check that the start and end values are 
        # exactly what we'd expect for this sequence
        if ((int(feature_list[0].start) != 1) or (int(feature_list[0].end) != 22) 
            or (feature_list[0].type != "INTRINSIC")):
                returnvalue = 3
                print "Data Error in first feature"
        
        if ((int(feature_list[1].start) != 23) or (int(feature_list[1].end) != 240) 
            or (feature_list[1].type != "SMART")):
                returnvalue = 4
                print "Data Error in second feature"
except:
    print "Failed to talk to SMART service"
    returnvalue = 1

if returnvalue == 0:
    print "Everything worked fine"
    
exit(returnvalue)

Things to note about this sample python client:

1. It uses SOAPpy to access the service. SOAPpy is a fairly low-level way of doing this, and it can be cumbersome to construct the right parameters for services, especially when they use complex types. But for this particular service it keeps the client code simple, and it’s one of the packages installed on the server for us, so we don’t need to do anything special in order to use it. If we really needed to use something else in Python to access our service, we would have to include the source files in the zip we upload.
2. The try:except: clause isn’t entirely necessary, since if the script crashes or aborts for any reason (for example, using SOAPpy if the service isn’t available, it may cause an exception at the point we try to get a proxy or invoke the doSMART function), then the registry’s harness will in fact catch this for us and record a failed test execution. But it doesn’t do any harm to trap this more elegantly within our own script.
3. This script returns 0 for Ok, 1 for ‘failed to talk to SMART for some reason’, and then 2, 3 or 4 if we could talk to the service but the results aren’t what we wanted. The 2, 3 and 4 return values are all interpreted by the registry as meaning the same test ‘warning’; we only return different values here so that if someone looks in detail at the log and compares it with our test script, its possible to see exactly which bit caused the problem.
4. Remember, you MUST explicitly exit your script with a meaningful return value. otherwise the harness will pick up whatever the default return value for your programming language happens to be.
5. Over half the lines in this example are comments; the actual code required is quite minimal.

Here's a similar example, but this time written in Perl. This script uses XMLCompile to access the Jaspar service.

#!/usr/bin/perl
# the first line of the script must tell us which language interpreter to use,
# in this case its perl

use strict;

# import the modules we need for this test; XML::Compile is included on the server
# by default.
use XML::Compile::WSDL11;
use XML::Compile::Transport::SOAPHTTP;

eval
{	
	# Retriving and processing the WSDL
	my $wsdl  = XML::LibXML->new->parse_file('http://api.bioinfo.no/wsdl/JasparDB.wsdl');
	my $proxy = XML::Compile::WSDL11->new($wsdl);
	
	# Generating a request message based on the WSDL
	my $getAllMatrices = $proxy->compileClient('getAllMatrices');
	
	# Calling the service and getting the response
	my $answer = $getAllMatrices->( Format => 'PFM', Database => 'CORE' );
	
	# If the response arrived, look for a specific value that is supposed to be equal to 40
	# If the value is 40, return 0 because the test passed.
	# If the value is something else, return 2 to indicate a warning.
	# If no answer has arrived, return 1 to indicate the test failed.
	if ( defined $answer ) {
		if (@{@{ $answer->{parameters}{Matrix} }[0]->{A}->{col}}[3] == 40){
			print "Passed\n";
			exit 0;
		} else {
			print "Unexpected data\n";
			exit 2;
		}
	} else {    
		print "Failed\n";
		exit 1;
	}
};

if ($@)
{
	print "Caught an exception\n";
	exit 1;
}

Things to note about this sample perl client:

1. It uses XML::Compile::SOAP to access the web service. We strongly recommend this approach as a more robust alternative to SOAP::Lite
2. Note the use of the 'eval' clause around much of the test body, and the 'if ($@)' test towards the end. Perl's standard return values are rather complex, and encode more information than we want here, so it's good practice to trap exceptions and make sure we return a '1'. Not doing this doesn't mean anything catastrophic will happen, since perl will exit with some non-zero number in any case, and the registry will interpret this as being a warning (whereas with the trap we can promote this to being an Error).

Here's a third example, written in Java. This code uses the Axis toolkit to access the DSSP service.

import org.apache.axis.client.Call;
import org.apache.axis.client.Service;
import javax.xml.namespace.QName;

public class TestClient {
  public static void main(String [] args) throws Exception {
	String endpoint =
		"http://utopia.cs.manchester.ac.uk/cgi-bin/dssp.cgi";

	Service  service = new Service();
	Call     call    = (Call) service.createCall();

	call.setTargetEndpointAddress( new java.net.URL(endpoint) );
	call.setOperationName(new QName("http://utopia.cs.manchester.ac.uk/", "runDSSPByID"));

	String ret = (String) call.invoke( new Object[] { "3EBX" } );

    if (ret.startsWith("==== Secondary Structure Definition by the program DSSP, updated CMBI version by ElmK / April 1,2000 ==== DATE="))
    {
	  System.out.println("Seems like the server is sending back something sane:");
	  System.out.println(ret);
	  System.exit(0);
    }
    else
    {
	  System.out.println("Got back invalid DSSP format:");
	  System.out.println(ret);
	  System.exit(1);
	}
  }
}

Things to note about this sample java client:

1. It uses the Axis toolkit to access the web service.
2. This is a simple example that shows direct access to a web service. It is recommended for anything other than such simple services to make use of Axis' WSDL2Java program to create this code for you.
3. Given that java is not an interpreted language, you will find no execution directive in this example (the '#!/usr/bin/something'). In order to use this code in a registry test, you must package a shell script that in turn executes this java program (i.e. calls 'java TestClient').

Programatically Adding/Updating Services and Service Tests

Prerequisites

• Python 2.5
• embrace_remote.py (EMBRACEremote.zip -- includes an example)

Adding/Updating Services and Service Tests

Services and service tests can be programmatically added to the EMBRACE registry by the Python script embrace_remote.py. When the script is executed without parameters it returns the following brief usage description:

In order to upload/change a service or service test, it is necessary to

• edit the EMBRACE username and password in the file embrace_remote.py,
• provide an XML file which describes the service or service test,
• in case files are attached to the service or service test, the path to the attachment has to be given as well, and
• implementations of service tests have to be archived and attached in a ZIP file.

The username and password are located within the script itself and not setable via command line options, because on a shared computer it would otherwise be possible for logged-in users to access this information by listing the currently running processes and their parameters. Since the username and password do not have to be repeatedly restated with each call to the script when being embedded within the script, it is possible to add/update a large amount of services and service tests by batch processing.

The actual information about a service or service test is provided to the script in an XML file. Examples of XML files that describe a service and a service test are given below.

A service or service test can now be specifying the path to the XML file and any additional uploads (such as ex_test.zip) as parameters to embrace_remote.py. A short status message will be printed when the script finishes, indicating the success or failure of the operation. For example:

For sucessfully adding services and service tests, it is necessary to change the username and password in embrace_remote.py. For large batch processing, it is advisable to test the outcome of a view script runs manually in order to make sure the desired changes are made to the registry.

Updating Information of Existing Services and Service Tests

In case the service, which is identified by its title, already exists in the EMBRACE registry, it will be overwritten with the information provided in the XML file. This is also the case for service tests, which are identified by their title as well as the title of the service they belong to.

Using HTML in XML

It is not possible to use plain HTML formatting in the XML files, since the XML document is checked against its DTD. Any additional HTML tags, for example <em>, are violating the DTD, so that it is necessary to escape additional formatting code as follows:

The description of the previous example will then be displayed in a web browser as:

Programatically Querying the EMBRACE Service Registry

The EMBRACE Service Registry Query Web Service

The EMBRACE Service Registry provides a query API that can be accessed in the following ways:

• XML-RPC - http://embraceregistry.net/services/xmlrpc
• REST - http://embraceregistry.net/services/rest

The web service allows you to programatically query the service registry in a number of ways, the following methods are provided:

ws_registry.searchWebServices

This method provides the ability to query the service registry by search phrase. The method will return details of services matching the search criteria.
This method takes the following input parameters:

• search_keys - the search string
• header - whether or not to summarise the data that is returned, TRUE returns summarised data, leave the parameter value empty to return full details.

This method returns an array of service details. If header parameter value is empty then the following data for each service is returned:

• nid (id assigned to the service by the registry)
• title (name of service)
• service_status (current status of the service, 0 = UNKNOWN, 1 = PASSED, 2 = WARNING, and 3 = FAILED)
• link (a link this service within the registry)

If header parameter value is empty the following additional data will be returned:

• created (date of service creation)
• version
• url (supported url)
• wsdl_url
• das_url
• rest_url

Example output data for input parameters: search_keys = "protein sequence"
Array
(
    [0] => Array
        (
            [nid] => 152
            [title] => BLASTp at SIB (protein query sequence(s) against protein database)
            [service_status] => 0
            [link] => http://www.embraceregistry.net/service/blastp-sib-protein-query-sequences-against-protein-database
            [created] => 1225793159
            [version] => 0.9.8 beta
            [support_url] => http://ch.embnet.org/software/aBLAST.html
            [wsdl_url] => http://wsembnet.vital-it.ch/soaplab2/services/embnet.blastp?wsdl
            [das_url] => 
            [rest_url] => 
        )

    [1] => Array
        (
            [nid] => 161
            [title] => tBLASTn at SIB (protein query sequence(s) against a nucleotide sequence database dynamically translated in all reading frames)
            [service_status] => 0
            [link] => http://www.embraceregistry.net/service/tblastn-sib-protein-query-sequences-against-nucleotide-sequence-database-dynamically-transla
            [created] => 1225796465
            [version] => 0.9.8 beta
            [support_url] => http://ch.embnet.org/software/aBLAST.html
            [wsdl_url] => http://wsembnet.vital-it.ch/soaplab2/services/embnet.tblastn?wsdl
            [das_url] => 
            [rest_url] => 
        )
)

To execute the example REST query click the link below.

Example REST Response for query http://embraceregistry.net/services/rest?method=ws_registry.searchWebServices&search_keys=protein%20sequence

<rest generator="xml_writer" version="1.0">
<status>success</status>
<response>
<item id="0">
<nid>152</nid>
<title>BLASTp at SIB (protein query sequence(s) against protein database)</title>
<service_status>0</service_status>
<link>http://embraceregistry.net/service/blastp-sib-protein-query-sequences-against-protein-database</link>
<created>1225793159</created>
<version>0.9.8 beta</version>
<support_url>http://ch.embnet.org/software/aBLAST.html</support_url>
<wsdl_url>http://wsembnet.vital-it.ch/soaplab2/services/embnet.blastp?wsdl</wsdl_url>
<das_url/>
<rest_url/>
</item>
<item id="1">
<nid>161</nid>
<title>tBLASTn at SIB (protein query sequence(s) against a nucleotide sequence database dynamically translated in all reading frames)</title>
<service_status>0</service_status>
<link>http://embraceregistry.net/service/tblastn-sib-protein-query-sequences-against-nucleotide-sequence-database-dynamically-transla</link>
<created>1225796465</created>
<version>0.9.8 beta</version>
<support_url>http://ch.embnet.org/software/aBLAST.html</support_url>
<wsdl_url>http://wsembnet.vital-it.ch/soaplab2/services/embnet.tblastn?wsdl</wsdl_url>
<das_url/>
<rest_url/>
</item>
</response>
</rest>

Example clients are attached at the bottom of this page.

ws_registry.checkServiceByID

This method provides the ability to check the status of a service given a service ID.
This method takes the following input parameters:

• id - the service id given by the service registry

This method returns an integer representing the status of the service. The following details are returned:

• service_status (current status of the service, 0 = UNKNOWN, 1 = PASSED, 2 = WARNING, and 3 = FAILED)

Example output data for input parameters: id = 58

1

To execute the example REST query click the link below.

Example REST Response for query http://embraceregistry.net/services/rest?method=ws_registry.checkServiceByID&id=58

<rest generator="xml_writer" version="1.0">
<status>success</status>
<response>1</response>
</rest>

Example clients are attached at the bottom of this page.

ws_registry.checkServiceByIDSet

This method provides the ability to check the status of a group of services given an array of service ID's.
This method takes the following input parameters:

• idset - an array of service id's given by the service registry

This method returns an integer array representing the status of the specified services. The following details are returned:

• service_status array (current status of the service, 0 = UNKNOWN, 1 = PASSED, 2 = WARNING, and 3 = FAILED)

Example output data for input parameters: idset = 58,101
Array
(
    [58] => 1
    [101] => 0
)

To execute the example REST query click the link below.

Example REST Response for query http://embraceregistry.net/services/rest?method=ws_registry.checkServiceByIDSet&idset=58,101

<rest generator="xml_writer" version="1.0">
<status>success</status>
<response>
<item id="58">1</item>
<item id="101">0</item>
</response>
</rest>

Example clients are attached at the bottom of this page.

ws_registry.getAllServiceHeaders

This method gets summarised details of all the registry services. This enables third party applications to get a full list of services held within the registry.
This method does not take input parameters.

This method returns an array of service headers giving summarised details of each service. The details that are returned are:

• nid (id assigned to the service by the registry)
• title (name of service)
• service_status (current status of the service, 0 = UNKNOWN, 1 = PASSED, 2 = WARNING, and 3 = FAILED)
• link (a link this service within the registry)

Example output data.
Array
(
    [0] => Array
        (
            [nid] => 186
            [title] => AffyDEGFinder
            [service_status] => 1
            [link] => http://embraceregistry.net/node/186
        )

    [1] => Array
        (
            [nid] => 62
            [title] => AIDA document retrieval service
            [service_status] => 0
            [link] => http://embraceregistry.net/node/62
        )

    [2] => Array
        (
            [nid] => 153
            [title] => BioMart MartService
            [service_status] => 1
            [link] => http://embraceregistry.net/node/153
        )
        .
        .
        .
        .
)

To execute the example REST query click the link below.

Example REST Response for query http://embraceregistry.net/services/rest?method=ws_registry.getAllServiceHeaders

<rest generator="xml_writer" version="1.0">
<status>success</status>
<response>
<item id="0">
<nid>186</nid>
<title>AffyDEGFinder</title>
<service_status>1</service_status>
<link>http://embraceregistry.net/node/186</link>
</item>
<item id="1">
<nid>62</nid>
<title>AIDA document retrieval service</title>
<service_status>0</service_status>
<link>http://embraceregistry.net/node/62</link>
</item>
<item id="2">
<nid>153</nid>
<title>BioMart MartService</title>
<service_status>1</service_status>
<link>http://embraceregistry.net/node/153</link>
</item>
.
.
.
</response>
</rest>

Example clients are attached at the bottom of this page.

ws_registry.getServiceDetails

This method returns the details of a specified service. The method will return either summarised or full details about the service
This method takes the following input parameters:

• id - the service id given by the service registry.
• header - whether or not to summarise the data that is returned, TRUE returns summarised data, leave the parameter value empty to return full details.

This method returns an array of service details. If header is set to TRUE then following data for each service is returned:

• nid (id assigned to the service by the registry)
• title (name of service)
• service_status (current status of the service, 0 = UNKNOWN, 1 = PASSED, 2 = WARNING, and 3 = FAILED)
• link (a link this service within the registry)

If header parameter is empty the following additional data will be returned:

• created (date of service creation)
• version
• url (supported url)
• wsdl_url
• das_url
• rest_url

Example output data for input parameters: id = 152
Array
(
    [nid] => 152
    [title] => BLASTp at SIB (protein query sequence(s) against protein database)
    [service_status] => 0
    [link] => http://embraceregistry.net/node/152
    [created] => 1225793159
    [version] => 0.9.8 beta
    [support_url] => http://ch.embnet.org/software/aBLAST.html
    [wsdl_url] => http://wsembnet.vital-it.ch/soaplab2/services/embnet.blastp?wsdl
    [das_url] => 
    [rest_url] => 
)

To execute the example REST query click the link below.

Example REST Response for query http://www.embraceregistry.net/services/rest?method=ws_registry.getServiceDetails&id=152

<rest generator="xml_writer" version="1.0">
<status>success</status>
<response>
<nid>152</nid>
<title>BLASTp at SIB (protein query sequence(s) against protein database)</title>
<service_status>0</service_status>
<link>http://embraceregistry.net/node/152</link>
<created>1225793159</created>
<version>0.9.8 beta</version>
<support_url>http://ch.embnet.org/software/aBLAST.html</support_url>
<wsdl_url>http://wsembnet.vital-it.ch/soaplab2/services/embnet.blastp?wsdl</wsdl_url>
<das_url/>
<rest_url/>
</response>
</rest>

WSDL Parsing and Verification Process

The EMBRACE Service Registry has an integrated WSDL Parsing and Verification System, this is tool that helps maintain high quality SOAP web services within the EMBRACE Service Registry. The key objectives of the system are as follows:

1. To inform service owners of non-compliant WSDL documents according to WS-I standards.
2. To provide a human readable representation of the WSDL document associated with a SOAP web service, which abstracts key information away from the WSDL representation and displays it on the web page, along with other detailed information derived by the registry.
3. To provide details of changes in the WSDL document over time, for example display the date that operation "X" was added to the web service, or the date that a port location changed. This feature does not only informs web service users of additional functionality, but it allows the service owner to verify the changes that have been detected.
4. To notify both the service owner and users of significant errors in WSDL documents that will prevent proper interaction between client and web service.

Notifications

Parsing and Verification

The system has multiple layers that feedback different information to both the user and service owner; warning messages will be displayed alongside the WSDL URL amongst the meta-data associated with a web service.

The example above shows that the WSDL parser found an issue with the WSDL document when attempting to parse it. This is also indicated by a red cross that follows the familiar traffic light system used elsewhere in the EMBRACE Service Registry.

Passed : the WSDL document has passed all parser and WS-I compliance testing.

Failed : either the parser or compliance testing found errors with the WSDL document that may affect the interaction between clients and the SOAP web service. Any errors found during either of these stages will be displayed as indicated above.

Warning : a problem has occurred in the verification process, and therefore the EMBRACE Service Registry cannot guarantee that clients can interact with the SOAP web service successfully. Any errors found will be displayed as shown above.

If the WSDL document passes the parsing phase the registry will display a human readable description of the WSDL document on the web service page, giving details of the service, ports, operations, messages, and types associated with web service.

Detecting Changes

The system checks a SOAP web service once per day for any changes that might have occurred. If a change has occurred then the service owner will be notified that the registry has detected this change, via email. The email will request that the service owner approves the change or otherwise. During this process the web service will be flagged as "Amber/Warning", meaning the registry cannot guarantee the stability of the web service. Once the service owner approves the change the service will return to "Green/Passed" unless the service owner rejects the changes, in which case it will go to "Red/Failed".

All changes that are detected are logged and displayed as shown below:

This output shows the date that the initial snapshot was taken for this web service and any subsequent changes that may have been detected. The system can detect changes to services, ports, operations, and message types.

Subscribe to a Service
If you wish to receive email updates about a particular web service, regarding its status and changes that are detected, you can subscribe to the service by logging into the EMBRACE Service Registry, selecting a service and opting to "Subscribe" in the top left hand corner of the service description. This will change your subscription status to "Subscribed", you will then be sent any future updates directly to your inbox.