What is the best XML structure for all round APIs?

Question

Please advise if you can.

I am creating an SMS web services API that will allow people to send SMS to their phone numbers. The request will be sent to the interface, then we will process this request based on the provided account information and loans available in their account.

We have two proposed XML structures for requesting an interface, and I would like you to advise which one is better, since we are going to swallow each other 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 two examples that you think are best suited for our API, regardless of the technology at the back. Please support your answer if you select it.

Answer 1

Interface A.

Interface B is essentially a list of keys / values, where, since interface A uses 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 evident from a look at A, but not from B.

Answer 2

I would review more ...

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

This allows the structure to assume 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 3

Another point, you should probably wrap the actual message in CDATA so that it is separate 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> 

That way, if the user enters invalid characters from an XML perspective, you will be protected.

Answer 4

There are a few things that say for interface A through interface B:

• it is easier to verify with the / DTD schema (especially if the type of text content is element dependent)
• the structure is clear
• easier to view it through XPath and convert via XSLT
• it’s easier to get attached to classes if you do such things

Of course, you can probably achieve all of the above with interface B, but that will be more cumbersome.

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

Beyond technical reasons, I believe that the design of the A interface is much more aesthetic. In interface B, tags are mostly useless because they are all the same. Therefore, all mmtag lines are dead weight.

Answer 5

Interface A. This is shorter.

Answer 6

Interface A ... I am a fan of attributes on the contents of a tag.

Answer 7

I would say that the second case is harder to read, since it hides implementation details in the attribute.

Answer 8

Interface A, for all the reasons stated by others. But I would suggest that ToAddress be an element that allows you to send the same message to multiple ToAddress's:

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

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