Migrating from 1.x to 2.0

View Source

2.0 is a rewrite. The API, the result shape and the dependencies all change.

Quick reference

1.x2.0
Soap.init_model(path, :file)Soap.load(path)
Soap.init_model(url, :url)Soap.load(url)
Soap.call(wsdl, op, params)Soap.call(client, op, params)
Soap.call(wsdl, op, {headers, params})Soap.call(client, op, params, soap_headers: headers)
Soap.call(wsdl, op, params, http_headers)Soap.call(client, op, params, http_headers: http_headers)
Soap.call(wsdl, op, params, [], http_opts)Soap.call(client, op, params, http_opts: http_opts)
{:ok, response} = Soap.call(...), then Soap.Response.parse(response){:ok, result} = Soap.call(...)
Soap.operations(wsdl) returned mapsSoap.operations(client) returns names
config :soap, :globals, version: "1.2"The WSDL decides. Pass version: "1.2" if it offers both
config :soap, :globals, http_client: XSoap.load(url, http: X), where X implements Soap.HTTP
allow_empty_soap_actions: trueNot needed
soap_version: "1.2"version: "1.2" on the call, and often not needed
skip_type_imports: trueNot needed for remote imports, which are skipped by default
raise OperationError{:error, %Soap.Error{reason: {:unknown_operation, name, available}}}

Remove config :soap, :globals from your configuration. Nothing reads it.

Results

Soap.call/4 now returns the decoded result, and it never returns {:ok, ...} for a failed call.

# 1.x
{:ok, response} = Soap.call(wsdl, "Add", %{intA: 2, intB: 3})
%{AddResponse: %{AddResult: "5"}} = Soap.Response.parse(response)

# 2.0
{:ok, %{"AddResponse" => %{"AddResult" => 5}}} = Soap.call(client, "Add", %{intA: 2, intB: 3})
In a result1.x2.0
KeysAtoms, with prefixes such as :"ns1:Result"Strings, with no prefixes
Numbers, booleans, datesStringsTheir schema type
One repeating elementA mapA list
Several repeating elementsA keyword listA list
xmlns declarationsMixed into the dataDropped
An attributeA plain keyA key starting with @
Text next to attributes"_value""#text"
xsi:nilA map of attributesnil

If you need the HTTP status, headers or raw body, use Soap.request/4, which returns a %Soap.Response{}. Its fields are status, headers, body, result, soap_headers and attachments. 1.x called the status status_code.

Errors

Situation1.x2.0
SOAP Fault{:ok, response} with a different result shape{:error, %Soap.Fault{}}
HTTP error with no Fault{:ok, response}, then a crash in parse{:error, %Soap.Error{reason: {:http_status, status, body}}}
Reply that isn't XMLA process exit in parse{:error, %Soap.Error{}}
Params that don't fit the schemaThe error text was sent to the server{:error, %Soap.Error{reason: {:invalid_param, path, message}}}, and nothing is sent
Missing WSDL fileMatchError{:error, %Soap.Error{}}
Transport failure{:error, reason}{:error, %Soap.Error{reason: {:transport, reason}}}

Requests

Most of these fix bugs, so check them if a server relied on the old output.

  • Field order now follows the schema. In 1.x, it followed map order.
  • The body wrapper is now the WSDL's element, such as tns:Pay. 1.x used its type's name.
  • Namespaces now follow the schema, including elements from imported schemas.
  • SOAPAction is now quoted, as the standard requires.
  • Custom HTTP headers are now added to the standard ones. In 1.x, they replaced all of them.
  • SOAP headers are now always sent. In 1.x, they vanished unless the WSDL declared a header part.
  • SOAP 1.2 now sends application/soap+xml.
  • Newlines and tabs in values are now kept.
  • Base64 fields now take raw bytes and encode them. If you were encoding them yourself, stop, or wrap the value in %Soap.Raw{}.
  • dateTime and date values are now really checked. To send one anyway, pass validate: false.

Imports

1.x fetched whatever a WSDL's imports pointed to. 2.0 follows relative imports, and fetches URLs only from the WSDL's own host. If your WSDL imports from another host:

Soap.load(url, allow_imports_from: ["schemas.example.com"])

Dependencies

2.0 uses Saxy for XML and Req for HTTP. sweet_xml, xml_builder and httpoison are gone. Your application can still use HTTPoison for its own requests. To send SOAP calls through it, write a small Soap.HTTP adapter. The README has an example.

Elixir 1.15 or newer is required.