Which XML structure is best suited for an all round API?

Question

Please advise if you can.

I am building an SMS web service API that will allow people to send SMS to their desired cellphone numbers. A request will be sent to the interface, we then process that request based on the account details provided and credits available on their account.

We have two proposed XML structures for the interface request and I would like you to advise which one is better as we are going at each others throats about it.

Interface A

print("<?xml version = "1.0" encoding="UTF-8" standalone="yes"?>
        <Message version="1.0">
            <ClientID>11111</ClientID>
            <PassPhrase>shjfkh</PassPhrase>
            <Request Type="sms" Refno="10" ToAddress="27732687745332">
                <Content>
                      hello world
                </Content>
            </Request>
        </Message> ");

Interface B

 print("<?xml version = "1.0" encoding="UTF-8" standalone="yes"?>
    <Message>
        <mmtag name="Version">1.0</mmtag>
        <mmtag name="ClientID">1001</mmtag>
        <mmtag name="RefNO">120</mmtag>
        <mmtag name="Encoding">base64</mmtag>
        <mmtag name="Type">SMS</mmtag>
        <mmtag name="Content">hello world</mmtag>
        <mmtag name="MSISDN">27781010102</mmtag>        
    </Message>");

Now, looking at the two examples, which do you think would be best-suited for our API interface, regardless of the technology in the back end. Please support your answer should you pick one.

Answer 1

Interface A. It's shorter.

Answer 2

Interface A... I'm a fan of attributes over tag content.

Answer 3

I would say that the second case is harder to read because it is hiding implementation details in an attribute.

Answer 4

I would revise A further...

<Message version="1.0" clientID="11111" passPhrase="shjfkh">
    <Request Type="sms" Refno="10" ToAddress="27732687745332">hello world</Request>
</Message>

This allows the structure to imply the possibility of multiple messages per message block.

<Message version="1.0" clientID="11111" passPhrase="shjfkh">
    <Request Type="sms" Refno="10" ToAddress="27732687745332">hello john</Request>
    <Request Type="sms" Refno="11" ToAddress="12345678901234">hello jane</Request>
</Message>

Answer 5

Another point, you probably should enclose the actual message in CDATA so that it is separated from your XML. Like this...

<Message version="1.0" clientID="11111" passPhrase="shjfkh">
    <Request Type="sms" Refno="10" ToAddress="27732687745332"><![CDATA[hello john]]></Request>
    <Request Type="sms" Refno="11" ToAddress="12345678901234"><![CDATA[hello jane]]></Request>
</Message>

This way if the user embeds illegal characters from XML perspective, you will be protected.

Answer 6

Interface A.

Interface B is essentially just a list of key/values, where as Interface A takes advantage of the structured nature of XML and provides meaning through the structure.

For example: ClientId is an attribute of the Message, not the Request itself. This is clear from looking at A, but not from B.

Answer 7

There are several things that speak for interface A over interface B:

• it's easier to be checked with a schema/DTD (especially if the type of the text content depends on the element)
• the structure is clearer
• it's easier to search through it via XPath and transform via XSLT
• easier to bind to classes, if you are into such things

Surely, you can probably achieve all things mentioned above with interface B, but it's going to be more cumbersome.

If you need arbitrary metadata that can be filled by the client, you can always add an element with key/value children to interface A.

Apart from all technical reasons, I think that the design of interface A is much more aesthetically pleasing. In interface B, the tags are basically useless, because they are all the same. Therefore, all the mmtag strings are dead weight.

Answer 8

Interface A, for all the reasons others have outlined. But I would suggest that ToAddress be an element, allowing the same message sent to multiple ToAddress's:

<Request Type="sms" Refno="10">
  <To>27732687745332</To>
  <To>1234567890</To>
  <Content>Hello world</Content>
  </Request>

As a nit-pick, I would suggest that attributes use a lead lowercase, and elements a lead uppercase... but that's just me.