incubator-esme-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Markus Kohler <markus.koh...@gmail.com>
Subject Re: Patch submitted, working towards API design
Date Tue, 03 Nov 2009 22:57:26 GMT
On Tue, Nov 3, 2009 at 9:38 PM, Ethan Jewett <esjewett@gmail.com> wrote:

> Hi Markus,
>
> Wow, thank you for all the comments. I really appreciate it.


You are welcome. Note that I would not consider me the absolute expert on
this topic. I studied a lot of RESTful API's lately, because I had to help
to define several ones, but I wouldn't say that I know exactly what works in
practice and where one can make comprises.


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

I think I would rather go back to api2user/USERID/tracks. I would even
consider to just have only
api2user/User/USERID return a list of URLs (HATEOS) looking like
api2/Track/trackID.



> 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?
>
> I was talking about bookmarking, because that is feature that you get "for
free" with a proper RESTful api.
Imagine someone wants to send a link to a particular message to someone else
then it's certainly usefull for the application to be able to now how to get
the data for that particular message. Of course It could happen that the
user user does not have the access rights to see the message, but that is a
completely orthogonal issue.


> > -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.
>
Agreed. Flex does not support it, also there are complicated ways around it.


>
> > - 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.
>
OK makes sense to me. Anyone has already looked whether SAML would be an
option here? It's becoming en vogue in Enterprise applications.

>
> > - "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?
>
See above. We should carefully avoid URL's that require too much knowledge
by the client.
For example api2/users/USERID/tracks looks like that the client knows that
to get the tracks for a user
the String "tracks" has to appended to the URL for the user. That's not
really "rResty".
Ok there's the argument that you might have USERID only and you would want
to jump to the tracks directly (would violate HATEOS), but because caching
can be used for most important User information,  this is not such a big
advantage (maybe I'm too vague here).

BTW, I would also definitely use Mime types.

Oh, and implementation wise, is there any technical (or legal) reason to not
use JAX-RS?
I think it should also work for Scala. With JAX-RS you could easily support
XML as well as JSON as well as other formats (I have seen a prototype of
Jersey supporting google protocol buffers) .



> Again, thank you for your feedback. I'll start incorporating it into the
> design!
>
It's my pleasure,
Greetings,
Markus

>
> Ethan
>

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message