Question

I’m trying to build a library that will build XML responses for an API. To help illustrate my problem, here are 2 sample API responses. the first for displaying menus, the second to display text.

<CiscoIPPhoneMenu>
  <Title>Title text goes here</Title>
  <Prompt>Prompt text goes here</Prompt>
  <MenuItem>
   <Name>The name of each menu item</Name>
   <URL>The URL associated with the menu item</URL>
  </MenuItem>
  <SoftKeyItem>
   <Name>Name of soft key</Name>
   <URL>URL or URI of soft key</URL>
   <Position>Position information of the soft key</Position>
  </SoftKeyItem>
</CiscoIPPhoneMenu>

…

<CiscoIPPhoneText>
  <Title>Title text goes here</Title>
  <Prompt>The prompt text goes here</Prompt>
  <Text>The text to be displayed as the message body goes here</Text>
  <SoftKeyItem>
   <Name>Name of soft key</Name>
   <URL>URL or URI of soft key</URL>
   <Position>Position information of the soft key</Position>
  <SoftKeyItem>
</CiscoIPPhoneText>

Okay, so my module outline looks like this:

class CiscoIPPhone(object): 
    def __init__(self, title=None, prompt=None):
        self.title = title
        self.prompt = prompt

class MenuItem(object):
    def __init__(self, name, url):
        self.name = name
        self.url = url

class CiscoIPPhoneMenu(CiscoIPPhone):
    def __init__(self, *args, **kwargs):
        super(CiscoIPPhoneMenu, self).__init__(*args, **kwargs)
        self.items = []

    def add_menu(self, name, url):
        self.items.append(MenuItem(name, url))

Note: for readability I removed the validation and sanitization these classes handle.

So my questions are:

1. I’m practically outputting a serialized representation of these objects, is doing it this considered wrong or bad practice?
2. Is there an design pattern that describes this kind of API interface class?
3. Is there a Python library that is elegantly written (Pythonic) that does something similar? (I’m thinking like a stripped down version of Django’s model serialization, or Django-Tastypie).

Answer 1

Most unfortunately, I cannot comment on the Python side of things.

Personally, I think this design is very acceptable.

There is one place where these messages are serialized and deserialized. The domain code using these classes creates one, fills it with the necessary data, and hands it (or its serialized representation) down to another component. When the actual serialization happens, the class itself checks whether all mandatory data has been set.

The classes are test-friendly. You just have to create a message, fill in some values, and check the XML-serialized version. The tests schema-check both the expectation and the actual output. These tests are the specification of the entire protocol.

The design lends itself to a nice fluent API:

new CiscoIPPhoneMenu()
    .withTitle("Title text goes here")
    .withPrompt("Prompt text goes here")
    ...

For reference purposes, Martin Reddy states in API design for C++ that, for a protocol or file format, to have one component that translates to or from the serialized representation. I think this is exactly the purpose of these classes.

If the serialized representation changes (e.g. from an XML format to a binary one), you are easily able to switch representation by e.g. providing a second ctor that accepts a format, or you anticipate that change and introduce a SerializationFormat enum.

I can readily imagine a python module that takes a XML schema ComplexType and generates the matching python class from it. Once I’ve tried to generate those classes in C# using Altova XML Spy; however this involved referencing a runtime DLL, and using another DLL just for this seemed too much overhead. This is essentially the way protobuf works, with the XML schema ComplexType being defined in an external DSL, and the serialization format a binary one.