Current section
Files
Jump to
Current section
Files
README.md
# Soap
[](https://hex.pm/packages/soap)
[](https://hexdocs.pm/soap/)
[](https://github.com/Nitrino/soap/blob/master/LICENSE.md)
A SOAP client for Elixir. It reads a WSDL, checks your params against its schema, and gives you back plain Elixir data shaped by that schema.
```elixir
{:ok, client} = Soap.load("http://www.dneonline.com/calculator.asmx?WSDL")
Soap.operations(client)
#=> ["Add", "Subtract", "Multiply", "Divide"]
Soap.call(client, "Add", %{intA: 2, intB: 3})
#=> {:ok, %{"AddResponse" => %{"AddResult" => 5}}}
```
Coming from 1.x? See the [migration guide](MIGRATING.md).
## Installation
```elixir
def deps do
[
{:soap, "~> 2.0"}
]
end
```
There's nothing to configure. Options go on the client or the call, so one application can talk to any number of services, in either SOAP version.
## Loading a service
```elixir
{:ok, client} = Soap.load("priv/service.wsdl")
{:ok, client} = Soap.load("https://example.com/service?wsdl", timeout: 10_000)
{:ok, client} = Soap.from_string(wsdl_xml)
```
Options you pass here become defaults for every call. A call's own options win.
### Imports
A WSDL is often loaded from somewhere you don't control, so imports are limited by default.
| Reference in a document | From a local file | From a URL |
|---|---|---|
| Relative path | Read | Fetched from the same host |
| `http` or `https` URL | Skipped | Fetched from the same host only |
| Absolute path, `file:`, others | Skipped | Skipped |
- `allow_imports_from: ["schemas.example.com"]` or `allow_imports_from: :all` allows more hosts.
- `import_root: "priv/wsdl"` keeps local imports inside a directory. Without it, a local WSDL can import from parent directories.
- With `import_root`, imports through symlinks below that directory are skipped.
- HTTP redirects follow the same host restrictions as imports. Relative imports resolve against the final URL.
- `client.service.unresolved_imports` lists what was skipped, and why.
- An import that's allowed but can't be read is an error. `ignore_failed_imports: true` accepts a partial model instead.
## Calling
```elixir
Soap.call(client, "CreateOrder", %{
"Customer" => %{"Name" => "Ann", "Phones" => ["555-1", "555-2"]},
"Total" => %{"@currency" => "EUR", "#text" => Decimal.new("10.50")},
"Date" => ~D[2026-11-04],
"Note" => nil
})
```
- Params can be a map, a keyword list, or a list of `{name, value}` or `{name, attributes, value}` tuples. Names can be atoms or strings.
- Elements go out in the order and namespaces the schema requires.
- A list repeats the element.
- `"@name"` is an attribute, and `"#text"` is an element's text next to its attributes.
- Missing, `nil`, empty and `[]` values follow the table below.
- Values go out in the form their type needs, including `Date`, `DateTime` and `Decimal`. Base64 and hex fields take raw bytes.
### Missing and empty values
| Param | Element sent |
|---|---|
| Key left out | None |
| `nil` | `xsi:nil="true"` if the schema says nillable, otherwise none |
| `""` | An empty element |
| `[]` | None if the element can repeat, otherwise an empty element |
In results, an element that's absent has no key, even one that can repeat. `xsi:nil` is `nil`, an empty simple element is `""`, and an empty complex one is `%{}`.
### Validation
A value that can't fit its type, or an element the schema doesn't allow, returns an error and nothing gets sent:
```elixir
Soap.call(client, "Add", %{intA: "two"})
#=> {:error, %Soap.Error{reason: {:invalid_param, "Add/intA", "\"two\" isn't a valid int"}}}
```
Missing required elements are allowed, because servers often accept less than their WSDL says. `validate: false` turns validation off.
### Options
| Option | Meaning |
|---|---|
| `:endpoint` | Send here instead of the address in the WSDL |
| `:port` | The `wsdl:port` to use, by name, when several offer the operation. It picks the binding and the address. By default it's the first one in the WSDL |
| `:version` | `"1.1"` or `"1.2"`, when the WSDL offers both |
| `:input` | The input's name, to choose between overloaded operations |
| `:soap_headers` | SOAP headers, in the same forms as params |
| `:http_headers` | Extra HTTP headers. One with a standard header's name replaces it |
| `:wsse` | WS-Security credentials |
| `:mtom` | Send every base64 field as an attachment |
| `:attachments` | Extra `%Soap.Attachment{}` parts |
| `:validate` | Check params against the schema. Defaults to true |
| `:timeout`, `:connect_timeout` | In milliseconds |
| `:follow_redirects` | Follow redirects on calls. Defaults to false |
| `:max_reply_size` | The largest reply to accept, in bytes, also once decompressed. Defaults to 100 MB. `:infinity` turns it off |
| `:http`, `:http_opts` | The HTTP adapter and its options |
A call's options replace the client's, except `:http_headers`, `:soap_headers`, `:http_opts` and `:telemetry_metadata`, which are merged by name or key, with the call winning. A header set to `nil` is removed, so a call can drop one the client sets:
```elixir
{:ok, client} = Soap.load(url, http_headers: [{"Authorization", "Bearer t"}])
Soap.call(client, "Ping", %{}, http_headers: [{"X-Request-Id", "42"}]) # sends both headers
Soap.call(client, "Ping", %{}, http_headers: [{"authorization", nil}]) # sends no Authorization
```
## Results
```elixir
{:ok, %{"GetOrderResponse" => order}} = Soap.call(client, "GetOrder", %{id: 7})
order
#=> %{
#=> "Id" => 7,
#=> "Paid" => true,
#=> "Created" => ~U[2026-11-04 10:00:00Z],
#=> "Lines" => [%{"Sku" => "A-1", "Quantity" => 2}],
#=> "Total" => %{"@currency" => "EUR", "#text" => "10.50"}
#=> }
```
- Keys are strings, so a reply can't create atoms. Prefixes are dropped, so a server changing its prefix changes nothing.
- An element that can repeat is always a list, even with one item.
- Values take their schema type. A value that doesn't parse stays a string.
- `xsd:decimal` stays a string, so no precision is lost. Call `Decimal.new/1` if you want a `Decimal`.
- `xsi:nil` is `nil`.
- `rpc/encoded` links (`multiRef`, `href`) are followed, and `soapenc:Array` becomes a list.
With no schema, as in `Soap.decode_response(nil, nil, status, headers, body)`, a repeated element is a list, a single one isn't, and values are strings.
For the HTTP status, raw body, SOAP headers and attachments, use `Soap.request/4`. To see what would be sent, use `Soap.build_request/4`.
## Errors
```elixir
case Soap.call(client, "Pay", params) do
{:ok, result} -> result
{:error, %Soap.Fault{code: code, message: message}} -> {:rejected, code, message}
{:error, %Soap.Error{reason: {:transport, reason}}} -> {:unreachable, reason}
{:error, %Soap.Error{reason: reason}} -> {:failed, reason}
end
```
A Fault or error that came from a reply keeps its HTTP `status`, `headers` and `body`, for example to read `Retry-After`.
Invalid params, wrongly shaped options, broken replies and network failures return errors instead of raising or exiting. `:http_opts` are the exception: they go to the HTTP adapter unchecked, and Req raises on one it doesn't know. A SOAP Fault is reported the same way at any HTTP status, in either SOAP version. `Soap.call!/4` raises these as exceptions instead.
## WS-Security
```elixir
token = Soap.WSSE.username_token("ann", "secret")
Soap.call(client, "GetOrders", %{}, wsse: token)
token = Soap.WSSE.username_token("ann", "secret", digest: true, timestamp: 300)
```
This supports `UsernameToken` with a plain password or a digest. Message signing and encryption aren't supported. Send plain passwords over HTTPS only.
## Attachments
```elixir
# MTOM: every base64 field goes as a binary part.
Soap.call(client, "Upload", %{"File" => bytes}, mtom: true)
# MTOM for one field, with a content type.
Soap.call(client, "Upload", %{"File" => %Soap.Attachment{data: bytes, content_type: "image/png"}})
# SOAP with Attachments: extra parts with no reference in the XML.
Soap.call(client, "Upload", %{}, attachments: [%Soap.Attachment{data: bytes}])
```
MTOM replies resolve into the result automatically. Other parts are in `Soap.request/4`'s `attachments`.
## Raw XML
```elixir
Soap.call(client, "Send", %{"Document" => %Soap.Raw{xml: prebuilt_fragment}})
Soap.call(client, "Send", params, soap_headers: [%Soap.Raw{xml: custom_header}])
```
Raw XML goes out unchecked and unescaped, so never build it from untrusted input.
## HTTP clients
Req is the default, and you can pass it options:
```elixir
Soap.load(url, http_opts: [req: [connect_options: [proxy: {:http, "proxy", 3128, []}]]])
```
To use another client, implement `Soap.HTTP` and pass it as `:http`. For HTTPoison:
```elixir
defmodule MyApp.SoapHTTP do
@behaviour Soap.HTTP
@impl true
def request(method, url, headers, body, opts) do
options = [
recv_timeout: opts[:timeout] || 5_000,
follow_redirect: opts[:follow_redirects] || false
]
case HTTPoison.request(method, url, IO.iodata_to_binary(body), headers, options) do
{:ok, %HTTPoison.Response{status_code: status, headers: headers, body: body}} ->
{:ok, %{status: status, headers: headers, body: body}}
{:error, %HTTPoison.Error{reason: reason}} ->
{:error, reason}
end
end
end
Soap.load(url, http: MyApp.SoapHTTP)
```
## Generating a client
```bash
mix soap.gen priv/calculator.wsdl --module MyApp.Calculator
```
This writes a module with one documented, typed function per operation:
```elixir
{:ok, client} = MyApp.Calculator.client()
MyApp.Calculator.add(client, %{"intA" => 2, "intB" => 3})
```
## Testing your code
`Soap.Test` answers calls with no network:
```elixir
{:ok, client} =
Soap.Test.client("priv/calculator.wsdl", fn request ->
assert request.operation == "Add"
assert request.params == %{"intA" => "2", "intB" => "3"}
Soap.Test.reply("AddResponse", %{"AddResult" => 5}, namespace: "http://tempuri.org/")
end)
assert {:ok, %{"AddResponse" => %{"AddResult" => 5}}} = Soap.call(client, "Add", %{intA: 2, intB: 3})
```
Handlers can also return `Soap.Test.fault("soap:Server", "boom")`, `{status, body}` or `{:error, :timeout}`.
## Telemetry
Each call emits `[:soap, :request, :start | :stop | :exception]`. Metadata holds the operation, version, URL, status and outcome, with credentials removed. To log calls:
```elixir
Soap.Telemetry.attach_default_logger(level: :info)
```
See `Soap.Telemetry`.
## Compatibility
- SOAP 1.1 and 1.2.
- WSDL 1.1, in document/literal, rpc/literal and rpc/encoded. WSDL 2.0 returns a clear error.
- WSDLs split across files with `wsdl:import`, `xsd:import` and `xsd:include`.
- XML in UTF-8, UTF-16 and ISO-8859-1.
Replies containing a DOCTYPE are refused, so external entities and entity bombs can't apply.
A reply over `:max_reply_size` returns `{:error, %Soap.Error{reason: :reply_too_large}}`. The limit also covers what a compressed reply expands to.
## Testing this library
The suite in `test/conformance/` runs against 1,400 real-world WSDLs, recorded replies, PHP's and node-soap's test suites, a raw socket server that sends broken replies, public services, and real servers in Docker: Apache CXF, PHP `SoapServer` and node-soap. See [test/corpus/README.md](test/corpus/README.md).
```bash
mix test
```
```bash
docker compose -f test/interop/docker-compose.yml up -d --build --wait
```
```bash
mix test --only interop
```
## Copyright and License
Copyright (c) 2017 Petr Stepchenko
This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See the [LICENSE.md](./LICENSE.md) file for more details.