esme-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ethan Jewett <>
Subject API2 - response format changes - request for input
Date Mon, 02 Nov 2009 20:16:04 GMT

This email is half warning of breaking changes and half request for
input. I'm working on major changes to the response format of the
current API in the API2 endpoint. Those changes amount to:

1. The current format wraps all responses in a tag that defines the
operation, the success/failure, and an optional message. I'm planning
to drop this completely, with an interim step of dropping all the
attributes and leaving the tag. In my opinion, the HTTP response code
should indicate the success/failure, the HTTP method and URL defines
the "operation", and the message ... well, I'm not sure what the
message is for.

Dropping this stuff and putting it into the actual HTTP codes is going
to involve dropping the use of the XMLApiHelper trait since that trait
doesn't seem to work this way at all. That change is coming in the
next patch.


2. The current API tends to use a lot of XML tag attributes to convey
information. Though this format is more concise, I would like to
switch to using nested tags to convey the information that is
currently conveyed through attributes. I find this more idiomatic
based on my use of other APIs, but it will also (I think) ease the
ability to convert the responses to JSON later on since JSON doesn't
seem to have built-in support for attributes. Thoughts on this?

The approach here is to write my own helper methods to convert ESME
objects (User for example) into XML Nodes, since if I override the
.toXml methods of the existing objects it will change the response
format of the current API and break things. I figure later I can write
a wrapper to match against the HTTP Accept header in order to convert
the Node into the return format that the client is requesting (default
to XML, but also provide JSON, for starters).


View raw message