Sometimes API vendors don't support REST and eveyone knows the WSDL-2-Apex parser is great...when it works...which is rarely. So sometimes you have to build a good old fashion XML request from scratch. I have been wondering what is the best way to do this and I'm curious what others think. Below are some options.

Let's say we need to construct this simple XML request. To make it a little tricker there is an optional element.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.myservice.com/services/MyService/">
   <soapenv:Header>
      <sch:API-KEY>awefa34r32asd</sch:API-KEY>
   </soapenv:Header>
   <soapenv:Body>
      <sch:FindCompanyByKeywordRequest>
         <sch:maxRecords>20</sch:maxRecords>
         <sch:keyword>united airlines</sch:keyword>
         <sch:state>MI</sch:state> <!-- optional -->
      </sch:FindCompanyByKeywordRequest>
   </soapenv:Body>
</soapenv:Envelope>

One way to do this is with strings. Something like this:

String API_KEY = 'awefa34r32asd'; /*yes, this should probably be stored in custom setting but it's here to keep demo simple*/
String maxRecordsValue = '20';
String keywordValue = 'united airlines';
String stateValue = 'MI';

String req = '';
req += '<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:sch="http://www.myservice.com/services/MyService/">';
req +=   '<soapenv:Header>';
req +=      '<sch:API-KEY>'+API_KEY+'</sch:API-KEY>';
req +=   '</soapenv:Header>';
req +=   '<soapenv:Body>';
req +=      '<sch:FindCompanyByKeywordRequest>';
req +=         '<sch:maxRecords>'+maxRecordsValue+'</sch:maxRecords>';
req +=         '<sch:keyword>'+keywordValue+'</sch:keyword>';
if(stateValue != null){
req +=         '<sch:state>'+stateValue+'</sch:state>';
}
req +=      '</sch:FindCompanyByKeywordRequest>';
req +=   '</soapenv:Body>';
req += '</soapenv:Envelope>';

Some thoughts. It doesn't seem very elegant and feels bloated but at the same time it is super simple. You can clearly see and understand the XML so it is also sort of self documenting.

Another option is using the DOM classes and this is what it would look like:

String API_KEY = 'awefa34r32asd';
String maxRecordsValue = '20';
String keywordValue = 'united airlines';
String stateValue = 'MI';

String soapNS = 'http://schemas.xmlsoap.org/soap/envelope/';
String sch = 'http://www.myservice.com/services/MyService/';

DOM.Document doc = new DOM.Document();
dom.XmlNode envelope = doc.createRootElement('Envelope', soapNS, 'soapenv');
envelope.setNamespace('sch', sch);

//Header
dom.XmlNode header = envelope.addChildElement('Header', soapNS, null);
dom.XmlNode apikey = header.addChildElement('API-KEY', sch, null).addTextNode(API_KEY);

//Body
dom.XmlNode body = envelope.addChildElement('Body', soapNS, null);
dom.XmlNode findCompanyByKeywordRequest = body.addChildElement('FindCompanyByKeywordRequest',sch,null);
dom.XmlNode maxRecords = findCompanyByKeywordRequest.addChildElement('maxRecords', sch, null).addTextNode(maxRecordsValue);
dom.XmlNode keyword = findCompanyByKeywordRequest.addChildElement('keyword', sch, null).addTextNode(keywordValue);
if(stateValue != null){
    dom.XmlNode state = findCompanyByKeywordRequest.addChildElement('state', sch, null).addTextNode(stateValue);
}

String req = doc.toXmlString();

If feels more structured but at the same time it feels like more work. I've parsed an XML response with the DOM class but have never created an XML object so there was a bit of guess and check to get every working but it wasn't too bad once I got it all figured out.

Now I know it's not always the best idea to judge level of effort required based on the number of lines of code and characters but the DOM method is more verbose. I'm guessing some will scoff at the string approach but it was fast to implement, is easy to understand, and is self documenting.

I'm curious what other people think about these two and any other approaches to constructing an XML document?

Thanks
-Jason