cXML isn't REST: lessons from building a SAP Ariba integration

I spent a good while building a connector that pushes supplier visibility data into SAP Ariba using cXML. If your background is web APIs, this is a different world, and most of the instincts you have are unhelpful.

The mental model is documents, not requests#

REST thinks in resources and operations. You act on a thing, you get a representation back.

cXML thinks in documents. You construct a complete, self-describing, schema-conformant document and transmit it. The document either satisfies the contract or it does not.

Once that clicks, the design follows. If the document is the unit of work, then the important operations are: build it correctly, verify it before sending, show it to a human, and keep a copy of what was sent. Those became the four features that mattered.

Strictness is the default, not an option#

A ProductReplenishmentMessage in cXML 1.2.033 has a defined structure. Elements appear in a specific order. Required attributes are required. There is no tolerant parsing and no "we ignored the field we did not recognise".

That is not a flaw. It is what makes a protocol viable across thousands of organisations that have never spoken to each other — but if your instinct is "send it and read the error", it is going to be a bad week.

Version numbers are load-bearing#

cXML 1.2.033 is a specific contract, not a rough indication. There is no version of this where approximately correct XML is accepted.

More importantly, version drift is a silent failure mode. Everything works, something changes on either side, and documents start being refused for reasons that have nothing to do with your data. Pin it, state it explicitly, and treat a version change as a change to the integration rather than a configuration tweak.

Move every check you can locally#

The single highest-value decision was validating documents against the expected structure before transmission.

A remote rejection tells you a document was refused. A local validation error tells you which element, in which position, failed which rule. The difference between those two feedback loops is the difference between an afternoon and a fortnight.

Adding an XML preview mattered for a similar reason. Being able to see the exact payload that will be transmitted turns debugging from inference into reading, and it lets a non-developer who understands the business data spot a problem the developer would not.

Keep a push history#

Integration failures are investigated late. Someone asks in March whether the December data went.

Without a record of every transmission and its response, that question is unanswerable. With one, it takes thirty seconds. It does nothing on the happy path and it is the only thing that matters when the question arrives.

If you are starting one of these#

• Read the schema properly. Not the summary — the actual structure.
• Build a validator before you build a sender.
• Make the payload visible to a human before it transmits.
• Log every exchange durably, including responses.
• Treat the version as part of the contract.
• Assume you will not get a helpful error, and design so you do not need one.

None of it is glamorous. All of it is what makes the integration diagnosable instead of mysterious.