esme-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ethan Jewett <esjew...@gmail.com>
Subject Re: Patch submitted, working towards API design
Date Tue, 03 Nov 2009 20:38:37 GMT
Hi Markus,

Wow, thank you for all the comments. I really appreciate it. Responses
and confirmations are inline:

On Tue, Nov 3, 2009 at 1:21 PM, Markus Kohler <markus.kohler@gmail.com> wrote:
> - it's not 100% clear to me what you mean with
> api2/user/tracks
> Do you mean api2/{USERID}/tracks where {USERID} is replaced by a valid
> USERID?
> or do you mean that depending on the authenticated user one would get back
> different results?
> I would not recommend to use the second approach, because that means you
> cannot bookmark the URLs anymore.

I mean the later (gets the tracks of the logged in user). In my mind
the true REST resource would be api2/users/USERID/tracks, and I would
be open to going back to this.

With regards to bookmarking, I do not see that as use-case we should
support in the API. What do you have in mind there?

> -Regarding PUT and DELETE not available on all clients one option would be
> to use google's approach in gdata and put an additional header into a POST
> request:
>
> X-HTTP-Method-Override: PUT

I like it. However, more and more HTTP client libraries are starting
to support PUT and DELETE requests, so I'd like to wait until there is
a demand before implementing.

> - as already commented  api2/session is not really Restful. I haven't read
> the details about why it's currently done this way, but wouldn't simple HTTP
> basic authentication work, at least if user and password are given?

Agreed that sessions aren't RESTful. On the other hand, there are some
backend optimizations that apparently benefit from sessions. It still
exists for two reasons:

1. It works currently and I'd like to keep the API working as I make
changes to it. I don't currently have another working method of
managing logins.
2. I don't yet understand the backend optimizations that this allows
and I'd like to understand that before ripping it out. Specifically,
the creation of a session currently starts up an Actor that I think is
used elsewhere in the API. I'm looking into this.

With regards to basic authentication, I don't want to allow the use of
basic authentication for the API. In general, token-based
authentication is a good idea for APIs as it makes explicit the
delegation that is going on when you allow an API client to act on
your behalf. There are things I would like to change about the way the
API uses the token to do authentication (either require HTTPS or don't
send the token in the clear, for starters), but I'm waiting on that
for the moment.

> - "Streaming" as far as I understand is about "push" functionality.
> I would not go as far as to say "polling is bad". Since twitter is not real
> time ESME would maybe not need to be real time as well. This means one could
> poll infrequently (every few minutes?) using conditional GET's, which would
> not be that inefficient. Comet has the disadvantage that without special
> server support (available in Jetty, but not in Netweaver CE for example)  it
> causes a lot of threads to be created on the server, which is also not
> really efficient.
> IMHO defining a pagination protocol would be more important.

Agreed, sort of. I'm defining API methods that will allow for pulling
down a list of messages or a specific message however, I agree with
David that we should provide better ways to access messages. Comet is
not currently turned on in the api2/ endpoint, but I was planning to
make it an option, though the server issue you bring up gives me
pause. What I'd really like to do is expose each message queue to
clients using AMQP (though what version I don't know).

I don't really know what the best approach is here, so I'm looking for input.

> In general I think it makes sense to define the URL pattern, but one has
> always to be careful to not fall into the trap and forget about HATEOS (
> http://blogs.sun.com/craigmcc/entry/why_hateoas).
> With proper HATEOS support, the exact URL's would be less important, and
> evolving the API  would be easier.

I've been keeping an eye on the SunCloud API development via Tim
Bray's blog but hadn't seen this angle. I'll have to think about it.
How are you thinking that this could be applied to the ESME API?

Again, thank you for your feedback. I'll start incorporating it into the design!

Ethan

Mime
View raw message