h2. Savon

p. Savon can be installed as a gem via:

bc. $ gem install savon

h4. Dependencies

bc. builder >= 2.1.2
crack >= 0.1.4

h2. Warning

p. To use this heavy metal library, you should be familiar with SOAP, WSDL and tools like soapUI.

h2. Instantiate Savon::Client

p. Instantiate Savon::Client, passing in the WSDL of your service.

bc. client = Savon::Client.new "http://example.com/UserService?wsdl"

h2. The WSDL

p. You can find out about the SOAP actions available on the webservice by using the WSDL object.

bc. client.wsdl.soap_actions.keys
=> [:get_all_users, :get_user_by_id, :user_magic]

p. Find out more about the "WSDL":http://wiki.github.com/rubiii/savon/wsdl object.

h2. Calling a SOAP action

p. Now, assuming your service applies to the default "Options":http://wiki.github.com/rubiii/savon/options, you can just call any available SOAP action.

bc. response = client.get_all_users

p. Savon lets you call SOAP actions using snake_case, because even though they will propably be written in lowerCamelCase or CamelCase, it just feels much more natural.

h2. The SOAP object

p. Pass a block to the SOAP request which expects a single variable and Savon will hand you the SOAP object to specify various SOAP-related options.

bc. response = client.get_user_by_id { |soap| soap.body = { :id => 666 } }

p. Learn more about the "SOAP":http://wiki.github.com/rubiii/savon/soap object.

h2. The WSSE object

p. Pass a block to the SOAP request which expects two variables and Savon will yield the SOAP and WSSE objects.

bc. response = client.get_user_by_id do |soap, wsse|
  wsse.username = "gorilla"
  wsse.password = "secret"
  soap.body = { :id => 666 }
end

p. Learn more about the "WSSE":http://wiki.github.com/rubiii/savon/wsse object.

h2. The response

p. The response is wrapped in an object to give you various options of handling it. Take a look at the "Response":http://wiki.github.com/rubiii/savon/response for more information.

h2. HTTP errors and SOAP faults

p. Savon raises a Savon::SOAPFault in case of a SOAP fault and a Savon::HTTPError in case of an HTTP error. More information about "Errors":http://wiki.github.com/rubiii/savon/errors.

h2. Logging

p. By default Savon logs each request and response to STDOUT. Specifying your own logger is as easy as it gets:

bc. Savon::Request.logger = RAILS_DEFAULT_LOGGER

Read more about "Logging":http://wiki.github.com/rubiii/savon/logging.

h2. RDoc and Wiki

p. Further information: "Wiki":http://wiki.github.com/rubiii/savon and "RDoc":http://rdoc.info/projects/rubiii/savon