savon

# Savon

Heavy metal SOAP client

[![CI](https://github.com/savonrb/savon/actions/workflows/ci.yml/badge.svg)](https://github.com/savonrb/savon/actions/workflows/ci.yml)
[![Gem Version](https://img.shields.io/gem/v/savon.svg)](https://rubygems.org/gems/savon)
[![Coverage Status](https://coveralls.io/repos/github/savonrb/savon/badge.svg?branch=main)](https://coveralls.io/github/savonrb/savon?branch=main)

Savon is a SOAP client for Ruby. [SOAP is the protocol](https://www.w3.org/TR/soap/) spoken by many enterprise systems. When they hand you a WSDL URL or file instead of a REST spec, it's SOAP. Savon reads the WSDL, maps available operations to Ruby symbols, converts Ruby hashes to SOAP envelopes and turns XML responses into hashes you can work with.

Full documentation is at [savonrb.com](https://savonrb.com).

## Installation

```ruby
gem 'savon', '~> 2.17'
```

## Usage

```ruby
require 'savon'

# Point Savon to a local or remote WSDL document
client = Savon.client(wsdl: 'https://service.example.com?wsdl')

# See what the service exposes
client.operations
# => [:find_user, :create_user]

# Make a request and work with the response
response = client.call(:find_user, message: { id: 42 })
response.body[:find_user_response]
# => { id: 42, name: "Hoff" }

# Savon raises a Savon::SOAPFault when the server returns a SOAP fault
rescue Savon::SOAPFault => e
  puts e.to_hash.dig(:fault, :faultstring)
```

Enable logging to see the raw SOAP envelopes. That's probably the single most useful thing while getting a new integration working:

```ruby
client = Savon.client(
  wsdl: 'https://service.example.com?wsdl',
  pretty_print_xml: true,
  log: true
)
```

### Authentication

Most enterprise services require authentication. Common options:

```ruby
# HTTP basic auth
Savon.client(wsdl: '...', basic_auth: ['user', 'secret'])

# WS-Security (WSSE)
Savon.client(wsdl: '...', wsse_auth: ['user', 'secret', :digest], wsse_timestamp: true)
```

See [Authentication](https://savonrb.com/version2/globals.html) on the website for HTTP digest, NTLM, and certificate-based options.

### Transport

Savon uses [HTTPI](https://github.com/savonrb/httpi) for HTTP by default. Since v2.17.0 you can opt-in to use Faraday by passing `transport: :faraday` which exposes the Faraday connection at `client.faraday` for you to configure. Savon is only adding some SOAP-specifics on top.

### MTOM/XOP attachments

To send a binary file with MTOM, pass a pre-built envelope with an `xop:Include` reference, set `mtom: true`, and give the matching attachment. The Content-ID must match the `cid:` href; set `content_id:` on the attachment when it differs from the filename:

```ruby
client.call(:upload,
  xml: <<~XML,
    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
                   xmlns:xop="http://www.w3.org/2004/08/xop/include">
      <soap:Body>
        <tns:upload><tns:file><xop:Include href="cid:doc1@example"/></tns:file></tns:upload>
      </soap:Body>
    </soa