Logo

Getting started with the Kidney SOAP API

This page describes the basics of using the kidney exchange SOAP API

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)
This is essentially a wrapper around the 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)
Finds an allocation of kidney donors to potential recipients. The data returned is in XML format and is described in more detail in the Output Formats section.
data
Holds a list of matched source patients, and their donors, to compatible target patients. The data must also include the score between donors and target patients and the donor's age. The various formats that the data can take are described in detail on the Input Formats page.
operation
This controls what type of allocation is returned. There are four possible parameters:
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_length
Indicates the length of a chain in an altruistic cycle. Default is 1.
The parameters below are only supported in versions 1.0.0 and above of the kidney_server (ruby) application and all version of the kidney_service application.
max_cycle_size
Indicates the maximum length of a cycle in an optimal solution. Default is 3.
output_format
The format of the data returned this can be either nhsbtv1 or nhsbtv2. Default is nhsbtv1.
v1.0.0