<div id="api_guide">
<h2>Getting started with the Kidney SOAP API</h2>

<p>This page describes the basics of using the kidney exchange SOAP API</p>

<div id="soap_contents">
  <h3>Table of Contents</h3>
  <ul>
    <li><a href="#soap_quick_start">Quick Start</a></li>
    <li><a href="#soap_request">SOAP Requests</a></li>
    <li><a href="#soap_response">SOAP Response</a></li>
    <li><a href="#soap_using">API Guide</a>
      <ul>
        <li><a href="#find_nhsbt"><code>find_nhsbt</code></a></li>
        <li><a href="#find"><code>find</code></a></li>
      </ul>
    </li>
  </ul>
</div>

<div id="soap_quick_start">
  <h3>Quick Start</h3>

  <p>
    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
    <a href="<%= "http://#{request.env['HTTP_HOST']}/kidney_exchange/wsdl" %>">
      <code><%= "http://#{request.env['HTTP_HOST']}/kidney_exchange/wsdl" %></code></a>. 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 <a href="#find_nhsbt"><code>find_nhsbt</code></a>. This
    method takes one parameter <code>data</code> which holds information about compatible patients and donors. The
    format of this information is described in detail in the section on
    <%= link_to 'input formats', :action => 'input_format' %>. 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
    <%= link_to 'output formats', :action => 'output_format' %>. The data returned can then be parsed using an
    XML parser to extract the required fields.</p>

    <p><strong>Note: </strong> Using the SOAP API the output data format cannot be changed and is always XML.</p>

  <p>
    An example of how the SOAP serviced can be consumed using Ruby and the
    <a href="http://github.com/rubiii/savon">Savon gem</a> is shown below:
      <pre class="brush: js">
require 'savon'

data = &lt;&lt;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://#{request.env['HTTP_HOST']}/kidney_exchange/wsdl" %>"

data = client.find_nhsbt do |soap|
	soap.body = { :data => data }
end
      </pre>
  </p>
</div>

<div id="soap_request">
  <h3>Soap Requests</h3>

  <p>SOAP requests are "envelopes" of specially formatted XML data posted to a URL.</p>

  <p>The SOAP Server Endpoint URL is <code><%= "http://#{request.env['HTTP_HOST']}/kidney_exchange/api" %></code></p>

  <p>SOAP requests to the kidney exchange service are a envelope with the format:</p>
    <pre class="brush: xml">
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;env:Envelope xmlns:wsdl="urn:ActionWebService"
                xmlns:env="http://schemas.xmlsoap.org/soap/envelope/"&gt;
    &lt;env:Body&gt;
      &lt;wsdl:Find&gt;
          &lt;data&gt;
                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
          &lt;/data&gt;
          &lt;operation&gt;optimal&lt;/operation&gt;
        &lt;/wsdl:Find&gt;
    &lt;/env:Body&gt;
  &lt;/env:Envelope&gt;
</pre>
</div>

<div id="soap_response">
  <h3>SOAP Response</h3>

  <p>The response form a soap request to the server takes the form shown below:</p>
    <pre class="brush: xml">
&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
  &lt;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"&gt;
    &lt;env:Body&gt;
      &lt;n1:FindResponse xmlns:n1="urn:ActionWebService"
                       env:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"&gt;

        &lt;return xsi:type="xsd:string"&gt;
        &lt;data&gt;
          &lt;algorithm&gt;Optimal set of exchanges with respect to the optimality criteria&lt;/algorithm&gt;
          &lt;output&gt;
            &lt;all_cycles&gt;
              &lt;cycle id="0" backarcs="0" weight="11.07442" alt=""&gt;
                &lt;pair&gt;
                  &lt;p&gt;1&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.03721&lt;/tb&gt;
                  &lt;dif&gt;3&lt;/dif&gt;
                  &lt;s&gt;3&lt;/s&gt;
                &lt;/pair&gt;
                &lt;pair&gt;
                  &lt;p&gt;2&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.03721&lt;/tb&gt;
                  &lt;dif&gt;3&lt;/dif&gt;
                  &lt;s&gt;2&lt;/s&gt;
                &lt;/pair&gt;
              &lt;/cycle&gt;
              &lt;cycle id="1" backarcs="0" weight="2.03872" alt=""&gt;
                &lt;pair&gt;
                  &lt;p&gt;1&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.01936&lt;/tb&gt;
                  &lt;dif&gt;0&lt;/dif&gt;
                  &lt;s&gt;1&lt;/s&gt;
                &lt;/pair&gt;
                &lt;pair&gt;
                  &lt;p&gt;3&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.01936&lt;/tb&gt;
                  &lt;dif&gt;0&lt;/dif&gt;
                  &lt;s&gt;1&lt;/s&gt;
                &lt;/pair&gt;
              &lt;/cycle&gt;
              &lt;cycle id="2" backarcs="0" weight="2.03698" alt=""&gt;
                &lt;pair&gt;
                  &lt;p&gt;2&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.01849&lt;/tb&gt;
                  &lt;dif&gt;0&lt;/dif&gt;
                  &lt;s&gt;1&lt;/s&gt;
                &lt;/pair&gt;
                &lt;pair&gt;
                  &lt;p&gt;5&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.01849&lt;/tb&gt;
                  &lt;dif&gt;0&lt;/dif&gt;
                  &lt;s&gt;1&lt;/s&gt;
                &lt;/pair&gt;
              &lt;/cycle&gt;
              &lt;cycle id="3" backarcs="1" weight="11.09494" alt=""&gt;
                &lt;pair&gt;
                  &lt;p&gt;1&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.02401&lt;/tb&gt;
                  &lt;dif&gt;0&lt;/dif&gt;
                  &lt;s&gt;2&lt;/s&gt;
                &lt;/pair&gt;
                &lt;pair&gt;
                  &lt;p&gt;4&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.03844&lt;/tb&gt;
                  &lt;dif&gt;3&lt;/dif&gt;
                  &lt;s&gt;1&lt;/s&gt;
                &lt;/pair&gt;
                &lt;pair&gt;
                  &lt;p&gt;2&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;b&gt;0&lt;/b&gt;
                  &lt;tb&gt;0.03249&lt;/tb&gt;
                  &lt;dif&gt;3&lt;/dif&gt;
                  &lt;s&gt;2&lt;/s&gt;
                &lt;/pair&gt;
              &lt;/cycle&gt;
              &lt;cycle id="4" backarcs="1" weight="9.07722" alt=""&gt;
                &lt;pair&gt;
                  &lt;p&gt;1&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.02401&lt;/tb&gt;
                  &lt;dif&gt;0&lt;/dif&gt;
                  &lt;s&gt;2&lt;/s&gt;
                &lt;/pair&gt;
                &lt;pair&gt;
                  &lt;p&gt;4&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;tb&gt;0.03721&lt;/tb&gt;
                  &lt;dif&gt;3&lt;/dif&gt;
                  &lt;s&gt;3&lt;/s&gt;
                &lt;/pair&gt;
                &lt;pair&gt;
                  &lt;p&gt;3&lt;/p&gt;
                  &lt;d&gt;-1&lt;/d&gt;
                  &lt;b&gt;1&lt;/b&gt;
                  &lt;tb&gt;0.016&lt;/tb&gt;
                  &lt;dif&gt;0&lt;/dif&gt;
                  &lt;s&gt;1&lt;/s&gt;
                &lt;/pair&gt;
              &lt;/cycle&gt;
            &lt;/all_cycles&gt;
            &lt;exchange_data&gt;
              &lt;entry weight="11.1142"
                     two_way_exchanges="1"
                     total_transplants="5"
                     three_way_exchanges="1"&gt;
                &lt;description&gt;(COIN) Optimal set of exchanges&lt;/description&gt;
                &lt;exchanges&gt;
                  &lt;cycle&gt;2&lt;/cycle&gt;
                  &lt;cycle&gt;4&lt;/cycle&gt;
                &lt;/exchanges&gt;
              &lt;/entry&gt;
            &lt;/exchange_data&gt;
          &lt;/output&gt;
      &lt;/data&gt;
     &lt;/n1:FindResponse&gt;
     &lt;/env:Body&gt;
&lt;/env:Envelope&gt;
    </pre>
  <p>The actual data returned depends on the parameters specified to the find command. More information is given in
    the following sections.</p>
</div>

<div id="soap_using">
  <h3>API Guide</h3>

  <p>Currently there are two methods exposed by the api namely <a href="#find"><code>find</code></a> and
    <a href="#find_nhsbt"><code>find_nhsbt</code></a>. Both methods carry out a similar task with
    <code>find_nhsbt</code> wrapping <code>find</code> with some parameters that should explicitly be used by NHSBT.</p>

  <p>The section below details the various options available for these methods.</p>

  <div id="methods">
    <div id="find_nhsbt" class="method">
      <div class="method_name"><code>find_nhsbt(data)</code></div>
      <div class="method_descr">
        This is essentially a wrapper around the <a href="#find"><code>find</code></a> 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
        <%= link_to 'Normal', {:action => 'output_format', :anchor => 'xml_normal'} %> section
        of the <%= link_to 'Output Formats', :controller => 'api', :action => 'output_format' %> page.
      </div>
     </div>
    <%= render :partial => 'find_template', :locals => {:out_format => 'XML', :method_name => 'find'} %>
  </div>
</div>
</div>