Si treballes amb integracions prou temps, tard o d'hora et trobaràs amb SOAP. No és cap relíquia arqueològica: bancs, asseguradores, administracions públiques i sistemes sanitaris continuen exposant milers de serveis SOAP en producció, i no desapareixeran a curt termini. Entendre què és, per què es va dissenyar així i en què es diferencia de REST et servirà per a dues coses molt concretes: integrar-t'hi quan toqui, i comprendre millor per què REST va prendre les decisions que va prendre. En aquesta lliçó veurem la mateixa consulta de la Botiga Aroma —obtenir les dades d'un cafè— resolta en tots dos estils, costat a costat.

1. Què és SOAP exactament
2. L'estructura del sobre: Envelope, Header i Body
3. El contracte: WSDL
4. La pila WS-*
5. El mateix cas costat a costat: consultar un cafè
6. Gestió d'errors: SOAP Fault davant dels codis HTTP
7. Taula comparativa completa
8. Quan continua tenint sentit SOAP
9. Quan triar REST
10. Façanes REST sobre serveis SOAP heretats

SOAP va néixer com a acrònim de Simple Object Access Protocol, encara que des de la versió 1.2 el W3C va deixar d'expandir les sigles (entre altres coses, perquè de simple en tenia poc). A diferència de REST, que és un estil arquitectònic, SOAP és un protocol: té una especificació formal que defineix exactament com ha de ser un missatge vàlid.

Els seus trets definitoris:

• Basat en XML: tot missatge és un document XML amb una estructura fixa.
• Independent del transport: pot viatjar sobre HTTP, però també sobre SMTP (correu), JMS (cues de missatges) o TCP pur. Aquesta neutralitat va ser un objectiu de disseny explícit.
• Orientat a operacions, no a recursos: s'invoquen mètodes com ara obtenirCafe o crearComanda, a l'estil RPC.
• Contracte formal descrit en WSDL, llegible per màquines, del qual es generen clients automàticament.
• Extensible mitjançant la pila WS-* per a seguretat, fiabilitat i transaccions.

Quan SOAP viatja sobre HTTP —el cas més habitual— fa servir sempre POST contra un únic endpoint. En reconeixeràs el patró: és exactament el nivell 0 del model de Richardson que vam veure a la lliçó anterior. HTTP actua com a simple túnel de transport.

Tot missatge SOAP és un "sobre" amb la mateixa anatomia:

• Envelope: l'element arrel. Identifica el document com a missatge SOAP.
• Header: opcional, conté metadades d'infraestructura. Aquí és on viuen WS-Security (signatures, credencials), els identificadors de transacció i l'encaminament. És l'equivalent conceptual a les capçaleres HTTP, però dins del missatge, cosa que permet que sobrevisquin a qualsevol canvi de transport.
• Body: obligatori, conté la càrrega útil: l'operació invocada amb els seus paràmetres, o el resultat.
• Fault: un element especial dins de Body que representa un error.

Aquesta separació entre Header i Body és més elegant del que sembla: permet que un intermediari processi la seguretat del Header sense tocar el contingut de negoci, i que el missatge signat continuï sent verificable encara que canviï de transport tres vegades al llarg del seu recorregut.

WSDL (Web Services Description Language) és un document XML que descriu formalment el servei: quines operacions ofereix, quins tipus de dades fa servir, quins missatges s'intercanvien i a quina adreça està disponible.

El seu valor pràctic és enorme i convé reconèixer-lo: a partir d'un WSDL, les eines generen automàticament el codi client complet en Java, C# o el llenguatge que sigui. El desenvolupador escriu servei.obtenirCafe("caf_001") i no veu ni un sol byte d'XML.

Un fragment simplificat del WSDL de la Botiga Aroma:

Observa la fortalesa real d'aquest enfocament: preuEuros està declarat com a xsd:decimal i estoc com a xsd:int. Un missatge que enviï "catorze cinquanta" és invàlid i es rebutja automàticament, sense escriure ni una línia de validació. En REST, aquest paper el compleixen avui OpenAPI i JSON Schema, però de manera opcional (lliçons 03-04 i 05-02).

Sobre SOAP s'hi va construir una família d'especificacions per cobrir necessitats empresarials que HTTP no resolia per si mateix:

Hi ha dues capacitats aquí que REST realment no iguala i convé reconèixer-ho sense complexos:

1. Seguretat a nivell de missatge. TLS xifra el canal: a cada salt intermedi el missatge es desxifra. WS-Security signa i xifra el contingut, de manera que pot travessar cinc intermediaris i continuar sent verificable a destinació. Per a una ordre de transferència bancària amb validesa legal, la diferència no és teòrica.
2. Transaccions distribuïdes. WS-AtomicTransaction permet coordinar una operació que abasta diversos serveis amb confirmació en dues fases. Al món REST es resol amb patrons de compensació, que són més simples d'operar però ofereixen garanties més febles.

El preu de tot això va ser la complexitat: les especificacions es comptaven per desenes, no totes les implementacions eren compatibles entre si, i desenvolupar sense un IDE que generés el codi era molt costós.

No hi ha res que aclareixi tant com veure la mateixa operació en tots dos estils. Volem obtenir les dades del cafè caf_001 de la Botiga Aroma.

La petició:

La resposta:

Coses que val la pena assenyalar:

• Es fa servir POST encara que l'operació només llegeix dades. Conseqüència: cap memòria cau intermèdia no pot reutilitzar aquesta resposta.
• L'endpoint és únic (/serveis/cafes); el cafè concret va al cos. No hi ha cap URL que identifiqui caf_001, així que no es pot enllaçar ni desar com a adreça d'interès.
• La capçalera SOAPAction indica quina operació s'invoca. És un mecanisme propi de SOAP, aliè a HTTP.
• Els espais de noms (xmlns) eviten col·lisions entre vocabularis, a canvi de molt soroll visual.
• La resposta és 200 OK fins i tot quan hi ha error de negoci: el resultat real és al cos.

La petició:

En cru:

La resposta:

La comparació de mides és demolidora: uns 900 bytes d'anada i tornada en SOAP davant d'uns 200 en REST, per exactament la mateixa informació. En una app mòbil que consulta el catàleg centenars de vegades, això es tradueix en dades, bateria i temps.

Però l'estalvi de bytes no és el més important. El que és decisiu és que en REST:

• El cafè té una URL pròpia que es pot compartir, enllaçar i provar des del navegador.
• L'operació és un GET, així que és cacheable (max-age=300) i segura de reintentar.
• El resultat es comunica amb el codi d'estat del protocol mateix.
• Qualsevol el pot provar amb curl en deu segons, sense generar codi ni instal·lar res.

Quan el cafè no existeix, SOAP respon amb un Fault:

Fixa't en la incoherència que arrossega el model: l'error és del client (ha demanat un cafè inexistent), però HTTP retorna 500, que vol dir "error del servidor". SOAP 1.1 hi obligava; SOAP 1.2 ho va flexibilitzar, però el patró continua viu en molts serveis. El resultat és que el monitoratge basat en codis HTTP no serveix: cal obrir l'XML per saber què ha passat.

En REST, el mateix error:

El codi d'estat ja ho diu tot per a les màquines, i el cos aporta el detall per a les persones. Un panell de monitoratge distingeix d'un cop d'ull entre "els clients demanen coses que no existeixen" (4xx) i "el meu servei està trencat" (5xx). El disseny detallat d'errors el veurem a 02-04 i 03-07.

Seria un error caricaturitzar SOAP com "allò antic i dolent". Hi ha contextos on les seves propietats continuen sent les adequades:

• Banca i sistemes de pagament interbancaris. Molts protocols financers exigeixen signatura digital del missatge amb validesa probatòria, i sovint l'estàndard del sector ja està definit en SOAP.
• Assegurances. Els intercanvis entre asseguradores i amb organismes reguladors estan estandarditzats en esquemes XML consolidats fa vint anys.
• Sanitat. HL7 i altres estàndards clínics tenen una llarga tradició XML, amb requisits estrictes d'estructura i validació.
• Administració pública. Molts serveis de facturació electrònica, notificacions i signatura estan definits com a serveis SOAP.
• Sistemes heretats. Un ERP amb quinze anys de vida exposa SOAP, i reescriure'l no és una opció realista.
• Requisits de transaccionalitat distribuïda. Quan de debò cal "tot o res" entre diversos serveis amb garanties fortes.
• Contractes que han de ser vinculants i verificables entre organitzacions, amb validació estricta i no-repudi.

El denominador comú: entorns regulats, amb contractes entre organitzacions, requisits legals de signatura i sistemes de llarga vida.

Per a tota la resta, i sens dubte per a un projecte nou orientat al web:

• APIs públiques que vols que la gent adopti sense fricció.
• Aplicacions web i mòbils, on el pes del missatge i la simplicitat del client importen.
• Contingut cacheable, com el catàleg de la Botiga Aroma.
• Ecosistemes de tercers: com més fàcil sigui començar, més integracions tindràs.
• Equips heterogenis amb llenguatges diferents i sense tooling empresarial uniforme.
• Iteració ràpida, on generar i regenerar contractes formals frenaria el desenvolupament.

Per a la Botiga Aroma la decisió és evident: la seva API la consumeixen un web, una app mòbil, un panell intern i socis externs. No hi ha signatura digital amb valor legal, ni transaccions distribuïdes entre organitzacions, i sí una necessitat clara de memòria cau i d'adopció fàcil. REST, sense dubtar-ho.

Un patró que trobaràs amb enorme freqüència a empreses mitjanes i grans: no es pot llençar el sistema SOAP heretat, però els clients moderns (mòbil, web, socis) no volen tocar XML. La solució és una façana REST que tradueix.

Suposem que la facturació de la Botiga Aroma la porta un ERP antic que només parla SOAP. La façana:

1. Rep GET /v1/comandes/com_5001/factura amb un token modern.
2. Valida permisos i tradueix la petició a un sobre SOAP amb les credencials que l'ERP espera.
3. Rep l'XML, n'extreu les dades i les converteix en JSON net amb noms coherents amb la resta de l'API.
4. Tradueix els Fault en codis d'estat HTTP adequats (404, 403, 503).
5. Hi afegeix memòria cau on tingui sentit, i alleuja la càrrega sobre un sistema antic i fràgil.

Avantatges: els clients nous veuen una API homogènia, el sistema heretat no es toca i es pot substituir per darrere sense que ningú se n'assabenti. Inconvenients: un salt més de latència, una peça més per mantenir i el risc que la façana acabi filtrant conceptes estranys del sistema antic (codis críptics, camps amb noms incomprensibles) si no es cuida el disseny.

Aquesta feina de traducció i homogeneïtzació és exactament una de les funcions d'un API gateway, que veurem a la lliçó 05-06.

• Dir "una API SOAP RESTful". Són coses de categories diferents: SOAP és un protocol, REST un estil. Un servei SOAP és, per construcció, al nivell 0 de Richardson.
• Menysprear SOAP per antic. Si et toca integrar-te amb banca o administració, hi trobaràs solucions sòlides que fa dècades que funcionen. L'actitud professional és entendre per què són així.
• Creure que TLS equival a WS-Security. TLS protegeix el canal punt a punt; WS-Security protegeix el missatge d'extrem a extrem, travessant intermediaris. Són garanties diferents.
• Reproduir SOAP amb JSON. Un endpoint únic que rep {"operacio": "..."} és SOAP sense els seus avantatges: tens la rigidesa del nivell 0 i cap de les seves garanties formals.
• Oblidar el Content-Type correcte en cridar un servei SOAP. SOAP 1.1 espera text/xml; SOAP 1.2, application/soap+xml. Confondre'ls produeix errors desconcertants.
• Dissenyar una façana REST com a calc del servei SOAP. Si la teva API exposa POST /v1/obtenirFacturaRequest, has traslladat el problema en comptes de resoldre'l.
• Consell: si treballes amb un servei SOAP, demana sempre el WSDL primer. Amb ell, eines com SoapUI o els generadors del teu llenguatge et donen un client funcional en minuts.

Donat aquest missatge, respon: (a) quina operació invoca?; (b) on viatgen les credencials i per què allà i no en una capçalera HTTP?; (c) es podria posar la resposta a la memòria cau?; (d) quin seria l'equivalent REST d'aquesta operació?

Per a cada escenari, decideix SOAP o REST i justifica-ho amb dos arguments concrets:

1. La Botiga Aroma vol que blogs de cafè mostrin el seu catàleg.
2. Un banc ha d'enviar ordres de transferència signades digitalment a un altre banc, amb no-repudi i validesa legal.
3. Aroma Mòbil necessita carregar el catàleg de pressa en xarxes mòbils lentes.
4. Una asseguradora ha d'intercanviar comunicats de sinistre amb un consorci que ja té definit un esquema XML estàndard.
5. Un servei intern d'inventari ha d'actualitzar l'estoc en tres sistemes i garantir que, si un falla, cap no queda modificat.

L'ERP heretat de la Botiga Aroma exposa aquestes tres operacions SOAP. Dissenya'n la façana REST equivalent indicant mètode, ruta, codi d'estat en cas d'èxit i quin error HTTP retornaries en el cas indicat.

Solució 1

• (a) Invoca LlistarComandesClient, i demana les comandes del client cli_842 des de l'1 de gener del 2026.
• (b) Les credencials viatgen al Header del sobre SOAP. La raó de disseny és la independència del transport: si el missatge viatja per SMTP o per una cua JMS en comptes d'HTTP, no hi ha capçaleres HTTP on posar-les. A més, així poden anar signades juntament amb el missatge i sobreviure als intermediaris.
• (c) No. És un POST a un endpoint únic, i ni les memòries cau HTTP ni els servidors intermediaris poden saber que en realitat és una lectura. Es perd del tot el mecanisme de memòria cau del protocol.
• (d) GET /v1/comandes?clientId=cli_842&des=2026-01-01, amb Authorization: Bearer abc123 i resposta 200 OK. Alternativa igualment vàlida: GET /v1/clients/cli_842/comandes?des=2026-01-01, que expressa la relació a la ruta.

Solució 2

1. REST. L'adopció per part de tercers ha de ser immediata (n'hi ha prou amb curl o fetch), i el catàleg és contingut cacheable, amb la qual cosa es redueixen càrrega i latència.
2. SOAP. Cal signatura a nivell de missatge amb no-repudi (WS-Security), que TLS no proporciona, i el més probable és que l'estàndard interbancari del sector ja estigui definit en SOAP.
3. REST. Els missatges JSON pesen una fracció d'un sobre SOAP, i les respostes del catàleg es poden posar a la memòria cau del dispositiu i d'un CDN.
4. SOAP. L'esquema XML ja existeix i és vinculant entre les parts; el WSDL genera clients validats automàticament i la validació estricta és un requisit, no una comoditat.
5. Depèn, i és el cas més matisat. Si s'exigeix atomicitat estricta entre sistemes heterogenis, WS-AtomicTransaction l'ofereix de manera estàndard. En una arquitectura moderna, però, l'habitual és resoldre-ho amb REST o missatgeria més un patró saga amb operacions de compensació, i acceptar consistència eventual a canvi de molta menys complexitat operativa. L'important és que la decisió sigui explícita.

Solució 3

Justificació:

• Obtenir factura: és una lectura, per tant GET. La factura es modela com a subrecurs de la comanda, cosa que en reflecteix la relació. Si encara no existeix, 404 Not Found, perquè el recurs sol·licitat no hi és.
• Anul·lar factura: no es fa servir DELETE, perquè anul·lar no és esborrar: la factura continua existint amb estat anul·lat, i en comptabilitat això és obligatori. L'anul·lació es modela com un subrecurs al qual es fa POST, enviant-hi el motiu al cos. Si ja estava anul·lada, 409 Conflict, que expressa exactament "l'estat actual del recurs impedeix aquesta operació". (Una alternativa defensable és PATCH /v1/factures/fac_88 amb {"estat":"anullada"}; el subrecurs resulta més expressiu quan l'acció exigeix dades pròpies com ara el motiu.)
• Llistar factures d'un client: GET sobre la subcol·lecció, amb l'any com a filtre a la query string, ja que modula la consulta i no identifica el recurs. Si el client no existeix, 404; si existeix però no té factures aquell any, 200 OK amb una llista buida, no 404: la col·lecció existeix, simplement és buida.

SOAP i REST responen a dues filosofies diferents: SOAP és un protocol formal, agnòstic respecte al transport, amb contracte WSDL i una pila d'extensions per a seguretat, fiabilitat i transaccions; REST és un estil que s'assenta en HTTP i n'aprofita els recursos, verbs, codis i memòria cau. Hem vist la mateixa consulta d'un cafè en tots dos, i hem comprovat que SOAP multiplica per quatre la mida del missatge, renuncia a la memòria cau i amaga el resultat dins del cos, mentre que REST converteix el cafè en un recurs adreçable, cacheable i provable des del navegador. També hem reconegut què fa millor SOAP —signatura de missatge d'extrem a extrem, validació estricta i transaccions distribuïdes— i per què continua viu a la banca, les assegurances, la sanitat i l'administració, així com el patró habitual d'embolcallar aquests serveis amb una façana REST.

Queda una última peça del mapa. A la lliçó següent, REST davant de GraphQL, gRPC i webhooks, veurem les alternatives contemporànies: quins problemes concrets de REST resol cadascuna, quins problemes nous introdueixen i per què avui el normal no és triar-ne una de sola, sinó combinar-les. Amb això tancarem el mòdul i estarem a punt per dissenyar l'API de la Botiga Aroma al mòdul 2.