API2 - response format changes - request for input

[Ethan Jewett <es...@gmail.com>]

All,

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.

Thoughts?

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).

Thanks,
Ethan

Re: API2 - response format changes - request for input

[Ethan Jewett <es...@gmail.com>]

Hi,

The changes are only to the /api2/ endpoint and I'm being careful not
to change the existing API. There are now two files in my local
checkout because I am reimplementing the XMLApiHelper trait, so that
file will show up in the next patch.

I'm also fairly certain that no one is currently developing any
clients based on the new API, but I did have a discussion about it on
Twitter with Daniel (I think), so I just want to make it clear on the
list that while this API is available, it is not stable. If you're
using it (and I'd appreciate people trying to use it and giving
feedback), you should probably make clear what you're doing on the
list so that we can coordinate..

With regards to examples: Absolutely, we need them on the wiki if
people are going to be able to implement against this in a sane way.
Currently I am documenting URLs, methods, and parameters, but I'll
start to document response formats as well as soon as they start to
stabilize. Thanks for the suggestion :-)

Ethan

On Tue, Nov 3, 2009 at 4:51 AM, Richard Hirsch <hi...@gmail.com> wrote:
> It might also be useful to have examples from the various API calls in
> the wiki so that users can get a feel for the data structures.
>
> D.
>
> On Tue, Nov 3, 2009 at 8:53 AM, Markus Kohler <ma...@gmail.com> wrote:
>> Hi all,
>> Will take a look at this later today.
>> Markus
>>
>> On Nov 3, 2009 6:02 AM, "Richard Hirsch" <hi...@gmail.com> wrote:
>>
>> Are the breaking changes just in the API2.scala code or in other scala
>> classes as well.
>>
>> Since I don't think anyone has built any clients using the new API, I
>> don't think we should have any problems.
>>
>> I'm glad to see any changes that make the API more REST-like (be it
>> using tags instead of attributes, etc.) inasmuch as I'm not a REST
>> expert, I'll leave you to judge whether the changes are appropriate or
>> not.  Maybe, you could reach out to others on twitter with more REST
>> experience and ask them.
>>
>> D.
>>
>> On Mon, Nov 2, 2009 at 9:16 PM, Ethan Jewett <es...@gmail.com> wrote: >
>> All, > > This email is h...
>>
>

Re: API2 - response format changes - request for input

[Richard Hirsch <hi...@gmail.com>]

It might also be useful to have examples from the various API calls in
the wiki so that users can get a feel for the data structures.

D.

On Tue, Nov 3, 2009 at 8:53 AM, Markus Kohler <ma...@gmail.com> wrote:
> Hi all,
> Will take a look at this later today.
> Markus
>
> On Nov 3, 2009 6:02 AM, "Richard Hirsch" <hi...@gmail.com> wrote:
>
> Are the breaking changes just in the API2.scala code or in other scala
> classes as well.
>
> Since I don't think anyone has built any clients using the new API, I
> don't think we should have any problems.
>
> I'm glad to see any changes that make the API more REST-like (be it
> using tags instead of attributes, etc.) inasmuch as I'm not a REST
> expert, I'll leave you to judge whether the changes are appropriate or
> not.  Maybe, you could reach out to others on twitter with more REST
> experience and ask them.
>
> D.
>
> On Mon, Nov 2, 2009 at 9:16 PM, Ethan Jewett <es...@gmail.com> wrote: >
> All, > > This email is h...
>

Re: API2 - response format changes - request for input

[Markus Kohler <ma...@gmail.com>]

Hi all,
Will take a look at this later today.
Markus

On Nov 3, 2009 6:02 AM, "Richard Hirsch" <hi...@gmail.com> wrote:

Are the breaking changes just in the API2.scala code or in other scala
classes as well.

Since I don't think anyone has built any clients using the new API, I
don't think we should have any problems.

I'm glad to see any changes that make the API more REST-like (be it
using tags instead of attributes, etc.) inasmuch as I'm not a REST
expert, I'll leave you to judge whether the changes are appropriate or
not.  Maybe, you could reach out to others on twitter with more REST
experience and ask them.

D.

On Mon, Nov 2, 2009 at 9:16 PM, Ethan Jewett <es...@gmail.com> wrote: >
All, > > This email is h...

Re: API2 - response format changes - request for input

[Richard Hirsch <hi...@gmail.com>]

Are the breaking changes just in the API2.scala code or in other scala
classes as well.

Since I don't think anyone has built any clients using the new API, I
don't think we should have any problems.

I'm glad to see any changes that make the API more REST-like (be it
using tags instead of attributes, etc.) inasmuch as I'm not a REST
expert, I'll leave you to judge whether the changes are appropriate or
not.  Maybe, you could reach out to others on twitter with more REST
experience and ask them.

D.

On Mon, Nov 2, 2009 at 9:16 PM, Ethan Jewett <es...@gmail.com> wrote:
> All,
>
> 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.
>
> Thoughts?
>
> 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).
>
> Thanks,
> Ethan
>