Getting started with the Kidney SOAP API
This page describes the basics of using the kidney exchange SOAP API
Table of Contents
Quick Start
First, you need to identify an appropriate SOAP client for your platform. Once you have
chosen a SOAP client you will normally have to point it to the wsdl file for this service - which can be found at
http://kidney.optimalmatching.com/kidney_exchange/wsdl. Now that you have a client,
and have it pointing to the correct location of the API, we need to call the appropriate method on the API -
usually find_nhsbt. This
method takes one parameter data which holds information about compatible patients and donors. The
format of this information is described in detail in the section on
input formats. The method call will then either return
an optimal set of exchanges that meets the requirements set out by NHSBT or an error. In
both cases the data will be returned in XML format as described in the section on
output formats. The data returned can then be parsed using an
XML parser to extract the required fields.
Note: Using the SOAP API the output data format cannot be changed and is always XML.
An example of how the SOAP serviced can be consumed using Ruby and the Savon gem is shown below:
require 'savon'
data = <<EOS
1 2 3 45
1 3 1 45
1 4 2 49
2 1 2 36
2 5 1 36
3 1 1 19
4 2 1 28
4 3 3 28
4 5 4 28
5 2 1 63
EOS
client = Savon::Client.new "http://kidney.optimalmatching.com/kidney_exchange/wsdl"
data = client.find_nhsbt do |soap|
soap.body = { :data => data }
end
Soap Requests
SOAP requests are "envelopes" of specially formatted XML data posted to a URL.
The SOAP Server Endpoint URL is http://kidney.optimalmatching.com/kidney_exchange/api
SOAP requests to the kidney exchange service are a envelope with the format:
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:wsdl="urn:ActionWebService"
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Body>
<wsdl:Find>
<data>
1 2 3 45
1 3 1 45
1 4 2 49
2 1 2 36
2 5 1 36
3 1 1 19
4 2 1 28
4 3 3 28
4 5 4 28
5 2 1 63
</data>
<operation>optimal</operation>
</wsdl:Find>
</env:Body>
</env:Envelope>
SOAP Response
The response form a soap request to the server takes the form shown below:
<?xml version="1.0" encoding="UTF-8" ?>
<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<env:Body>
<n1:FindResponse xmlns:n1="urn:ActionWebService"
env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<return xsi:type="xsd:string">
<data>
<algorithm>Optimal set of exchanges with respect to the optimality criteria</algorithm>
<output>
<all_cycles>
<cycle id="0" backarcs="0" weight="11.07442" alt="">
<pair>
<p>1</p>
<d>-1</d>
<tb>0.03721</tb>
<dif>3</dif>
<s>3</s>
</pair>
<pair>
<p>2</p>
<d>-1</d>
<tb>0.03721</tb>
<dif>3</dif>
<s>2</s>
</pair>
</cycle>
<cycle id="1" backarcs="0" weight="2.03872" alt="">
<pair>
<p>1</p>
<d>-1</d>
<tb>0.01936</tb>
<dif>0</dif>
<s>1</s>
</pair>
<pair>
<p>3</p>
<d>-1</d>
<tb>0.01936</tb>
<dif>0</dif>
<s>1</s>
</pair>
</cycle>
<cycle id="2" backarcs="0" weight="2.03698" alt="">
<pair>
<p>2</p>
<d>-1</d>
<tb>0.01849</tb>
<dif>0</dif>
<s>1</s>
</pair>
<pair>
<p>5</p>
<d>-1</d>
<tb>0.01849</tb>
<dif>0</dif>
<s>1</s>
</pair>
</cycle>
<cycle id="3" backarcs="1" weight="11.09494" alt="">
<pair>
<p>1</p>
<d>-1</d>
<tb>0.02401</tb>
<dif>0</dif>
<s>2</s>
</pair>
<pair>
<p>4</p>
<d>-1</d>
<tb>0.03844</tb>
<dif>3</dif>
<s>1</s>
</pair>
<pair>
<p>2</p>
<d>-1</d>
<b>0</b>
<tb>0.03249</tb>
<dif>3</dif>
<s>2</s>
</pair>
</cycle>
<cycle id="4" backarcs="1" weight="9.07722" alt="">
<pair>
<p>1</p>
<d>-1</d>
<tb>0.02401</tb>
<dif>0</dif>
<s>2</s>
</pair>
<pair>
<p>4</p>
<d>-1</d>
<tb>0.03721</tb>
<dif>3</dif>
<s>3</s>
</pair>
<pair>
<p>3</p>
<d>-1</d>
<b>1</b>
<tb>0.016</tb>
<dif>0</dif>
<s>1</s>
</pair>
</cycle>
</all_cycles>
<exchange_data>
<entry weight="11.1142"
two_way_exchanges="1"
total_transplants="5"
three_way_exchanges="1">
<description>(COIN) Optimal set of exchanges</description>
<exchanges>
<cycle>2</cycle>
<cycle>4</cycle>
</exchanges>
</entry>
</exchange_data>
</output>
</data>
</n1:FindResponse>
</env:Body>
</env:Envelope>
The actual data returned depends on the parameters specified to the find command. More information is given in the following sections.
API Guide
Currently there are two methods exposed by the api namely find and
find_nhsbt. Both methods carry out a similar task with
find_nhsbt wrapping find with some parameters that should explicitly be used by NHSBT.
The section below details the various options available for these methods.
find_nhsbt(data)find method. Parameters have
been supplied that currently match the requirements of the NHSBT allocation. This call will return
exactly one allocation that should, in general, be the allocation chosen by NHSBT as part of their
matching run. Usage of this method is recommended as calling this will allow the various parameters to be
changed in the future without the need for the client code to change. An example of the output produced
by calling this method can be found in the
Normal section
of the Output Formats page.
find(data, operation, altruistic_chain_length)dataoperation- optimal
- returns a solution that is defined as optimal in the optimality criteria section.
- maxcard
- returns a solution that has maximum cardinality and subject to this maximum weight, i.e. is not constraint by maximising the effective number of pairwise exchanges. More details of this can be found in the maxcard sub-section of the optimality criteria section.
- pairs
- returns an optimal solution involving only pairwise exchanges.
altruistic_chain_length1.0.0
and above of the kidney_server (ruby) application and all version of the
kidney_service application.max_cycle_sizeoutput_formatnhsbtv1 or nhsbtv2.
Default is nhsbtv1.