skip to content

When choosing between SOAP and REST for a new tax-authority integration that offers both, which factors should decide, and when is SOAP the better answer?

level: seniorimportance: should knowfreq 30%

answer

  1. who owns the contract
  2. what must cross intermediaries
  3. transports beyond HTTP
  4. cost of the XML toolchain
  5. the counterpart's estate

basics

~20 s

Decide on the integration's needs: SOAP wins where a strict WSDL contract, protection that must survive intermediaries, a non-HTTP transport or the counterpart's own SOAP estate matters. Otherwise REST's HTTP semantics, caching and lighter tooling usually win.

solid answer

~50 s

I would score the two interfaces on named factors rather than taste. **Contract**: a WSDL with XML Schema gives strict typing and generated stubs; an OpenAPI description is lighter and evolves more loosely. **Errors**: typed SOAP faults against status codes that HTTP tooling understands. **Security**: TLS plus bearer tokens protects each hop; WS-Security can sign or encrypt chosen message parts end to end, which matters when the message passes intermediaries or must be kept as evidence. **Transport and reliability**: SOAP also runs over message queues and has WS-ReliableMessaging. **Cost**: XML payloads and heavier stacks against JSON and plain HTTP clients. SOAP is the better answer when the authority's certification, examples and support are built around the WSDL, when filings must carry signatures that survive intermediaries, or when a queue binding is required; otherwise REST, isolated behind an adapter either way.

go deeper

for a junior

Recall the main axes - contract, errors, security, caching, payload size - and that a partner's existing interface often decides the choice.

for a middle

Explain each factor with its mechanism: WSDL against OpenAPI, faults against status codes, TLS per connection against message-level protection.

for a senior

Run the decision as a review: establish which interface is primary, what must survive intermediaries, and keep the choice behind an adapter so it stays reversible.

for a principal

Treat it as a portfolio choice: how many partners share the contract, who bears the cost of change, and when a counterpart's mandate outweighs internal preference.

## Frame the decision first A counterpart that offers both interfaces usually offers them unequally: one is older, better documented or used by most other filers. Before comparing styles, establish three facts: 1. **Which interface is primary** for the counterpart - which one their conformance testing, examples and support desk assume. 2. **What the message must prove** after it leaves your system - only that it arrived over a secure connection, or who sent exactly which content. 3. **Which path it travels** - straight to the counterpart, or through gateways, brokers and queues that read or terminate the connection. The answers often settle the question before any style argument starts. If the counterpart's conformance suite, sample messages and support knowledge are all SOAP, the REST interface is the riskier path however pleasant it looks. Interviewers want a reasoned choice on named factors, not "REST is modern". ## The factors | Factor | Points towards SOAP | Points towards REST | |---|---|---| | Contract | WSDL with XML Schema; strict validation; generated typed clients | OpenAPI description or none; looser, tolerant evolution | | Errors | Typed faults declared in the contract | Status codes every HTTP component understands, plus a body | | Security | WS-Security over chosen message parts, end to end across intermediaries | TLS per connection plus bearer tokens; simpler key handling | | Caching and retries | None at the HTTP layer; every call is a POST | GET caching; idempotent methods a client may retry | | Transport and reliability | HTTP or message queues; WS-ReliableMessaging available | HTTP only; reliability built in the application | | Payload and tooling | XML envelopes; base64 or MTOM for binary parts; heavier stacks | JSON; any HTTP client; easy debugging | **Security is one row, not the decision.** TLS protects a connection, so a message is in clear text wherever a connection ends - at a load balancer, a broker, a gateway. WS-Security, whose stated goal is "end-to-end message content security and not just transport-level security", protects chosen parts of the message itself across SOAP intermediaries. Note what it does not claim: the WS-Security specification lists **non-repudiation** among its non-goals. A signature is evidence of origin and integrity; whether it carries legal weight is the counterpart's and the regulator's policy. ## When SOAP is the better answer - **The counterpart's estate is SOAP.** Its WSDL is the reference contract, its test environment validates envelopes, and the REST interface is newer or thinner. Choosing the secondary interface means discovering its gaps alone. - **Messages must stay protected or provable beyond one connection.** A filing that passes through intermediaries, or that both sides archive with its signature, fits message-level protection. - **The transport is a queue, not a request.** SOAP over Java Message Service 1.0 is a W3C Recommendation; a resource-oriented HTTP API has no standard equivalent. - **Many partners share one strict contract.** A WSDL with XML Schema, validated on both sides, catches mismatches before production in a way a loosely documented JSON API does not. - **The counterpart already uses WS-ReliableMessaging or other WS-* features** your integration must take part in. ## When REST is the better answer - The integration is **request-response over the public internet** and TLS to the counterpart's edge meets the security requirement. - **Reads dominate**, and caching or simple retries matter. - The team must **onboard quickly** with ordinary HTTP tooling, and the counterpart's REST interface is complete and supported. - **Payload size or parsing cost** matters - mobile clients, high volumes, large documents. ## Keep the choice reversible Whichever wins, contain it: 1. Put the counterpart's interface behind an **adapter** in your system, so internal services never see envelopes or the counterpart's error model. 2. **Map** SOAP faults or HTTP error responses to your own error types at that boundary. 3. **Pin** the contract version you integrated against and test against it, so a counterpart change shows up in tests rather than in production. ## Mistakes in such reviews - Choosing REST and then re-implementing message signing ad hoc in JSON, without a standard to verify against. - Choosing SOAP for a reason it does not meet, such as "SOAP is more secure" when only TLS is configured. - Ignoring the payload and toolchain cost of XML for a high-volume, low-value flow. - Treating the decision as permanent instead of isolating it.

  • The team argues SOAP is more secure than REST. How do you answer?
    Neither style is secure by itself. A SOAP service with only TLS has the same protection as a REST API with TLS. SOAP's difference is that WS-Security can sign or encrypt chosen message parts so they stay protected across intermediaries and can be stored with the message. If no requirement needs that, the claim does not favour SOAP.
  • The authority's REST interface lacks two operations that its SOAP interface has. What do you do?
    Treat the SOAP interface as primary for this integration, or integrate both behind one adapter and use SOAP only for the missing operations, documenting why. Building workarounds around missing operations usually costs more than a SOAP client, and the counterpart's fuller interface is also the one its support team knows best.

saying these in an interview costs you the question

  • SOAP is more secure than REST by design.
  • WS-Security guarantees legal non-repudiation of every signed message.
  • REST is always the right choice for a new integration because it is newer.
  • A WSDL contract makes integration effortless because the client is generated.
  • TLS protects a message end to end, even across gateways that terminate it.