Mailing-List: contact esme-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: esme-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: domain of esjewett@gmail.com designates
 209.85.160.41 as permitted sender)
DomainKey-Signature: a=rsa-sha1; c=nofws;
        d=gmail.com; s=gamma;
        h=mime-version:in-reply-to:references:date:message-id:subject:from:to
         :content-type:content-transfer-encoding;
        b=hYWH/R5B2MEpgjcE5+B+BbUQ7UnyUnI4R7OCMueI7ks0R47hJ2Nem1rdFLj7rojQhz
         n2eHfbkY5fGIBl+3Pu03KYFAIAQp27WnvDjy1OCsKKfuIWRfAhOgTqI+Jt+03aFSyKhz
         QswQWxr5e5I/+omzeTaxMK6BuR5ikWdOikXJw=
MIME-Version: 1.0
In-Reply-To: <cdbebedf0911101610u5a3edcc0j9b9fb6b02321e618@mail.gmail.com>
References: <68f4a0e80910251728te9c1248j10f1aa99c9f7cd2e@mail.gmail.com>
	 <771905290911040158v539c016em1221acf54bbb5509@mail.gmail.com>
	 <cdbebedf0911040635y76afdeb5yd24640026b613381@mail.gmail.com>
	 <771905290911040809n24ad6a6ey9a00c1d819dfbb15@mail.gmail.com>
	 <cdbebedf0911040914w53014c35qad318a9bda4eb6b6@mail.gmail.com>
	 <c7fc82820911041014y33036dd2vda4ce00da23e3ab6@mail.gmail.com>
	 <68f4a0e80911050530p2b3c483cr7c79f7f2a6889e60@mail.gmail.com>
	 <cdbebedf0911051510o43d7d70co7905601240c8f49e@mail.gmail.com>
	 <68f4a0e80911061207u3b482c83y738861dad4cf1f62@mail.gmail.com>
	 <cdbebedf0911101610u5a3edcc0j9b9fb6b02321e618@mail.gmail.com>
Date: Sun, 15 Nov 2009 11:36:00 -0500
Message-ID: <68f4a0e80911150836u44b18f5crbbf72da125b19f64@mail.gmail.com>
Subject: Re: Patch submitted, working towards API design
From: Ethan Jewett <esjewett@gmail.com>
To: esme-dev@incubator.apache.org
Content-Type: text/plain; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable

I've updated the API 2.0 design page with something very similar to
this: http://cwiki.apache.org/confluence/display/ESME/API+2.0+-+Design

What do people think of the example/proposal on that page? It does
make the computationally expensive history request require the
addition of an extra parameter.

Ethan

On Tue, Nov 10, 2009 at 7:10 PM, David Pollak
<feeder.of.the.bears@gmail.com> wrote:
> On Fri, Nov 6, 2009 at 12:07 PM, Ethan Jewett <esjewett@gmail.com> wrote:
>
>> On Thu, Nov 5, 2009 at 6:10 PM, David Pollak
>> <feeder.of.the.bears@gmail.com> wrote:
>> >
>> > Lift's CometActors are meant as UI components, not as HTTP API
>> components.
>> > In fact Lift's CometActor changes behavior depending on the JavaScript
>> > library used for the given application. =A0But the existing HTTP APIs =
(the
>> > ones that I wrote) that support long polling do not use CometActors.
>> =A0What
>> > they do is they register themselves as a listener on the User object,
>> just
>> > as the CometActor does, and just as an AMQP or XMPP component could. =
=A0The
>> > CometActors are used for the UI. =A0Other Actors are used for APIs. =
=A0But at
>> > the end of the day, they're listeners that support asynchronous update
>> > messages.
>>
>> Gotcha. I checked out the code and I see that now (that it isn't using
>> the front-end comet-actor). I'm going to plug the streaming interface
>> back into the api2/ endpoint - I think I'm going to make it use the
>> same URL and response format as the messages resource, with some
>> additional indicator to show that the client wants the long-poll
>> option. Here's what I'm thinking as far as reconciling the
>> REST/Streaming-HTTP approaches (ignore the URL pattern and the use of
>> a query string instead of a header for the moment):
>>
>> Client makes "long-polling" request:
>> GET http://esme.org/api2/messages?longpoll=3DT
>>
>>
> How about:
> GET http://esme.org/api2/messages // long poll
>
> GET http://esme.org/api2/messages?timeout=3D20 // 20 second timeout
>
> So, by default, the server chooses the request timeout, but the client ca=
n
> modify the timeout based on its needs.
>
> This also makes the long polling the default, but allows you to deal with
> other clients. =A0It's also not a binary thing, but a tuneable parameter.
>
>
>> This request only returns when a new message shows up for the user. So
>> what if the client wants to grab the last X messages for the user (to
>> populate a timeline, for example)? Then (after it verifies that the
>> long-poll is set up), it:
>>
>> GET http://esme.org/api2/messages
>>
>> This way, clients that don't need or don't support long-polling
>> functionality don't need to use it (YQL only supports 30 seconds of
>> processing, for example, so not a very long poll) and clients that
>> don't need all the old messages in the mailbox can just tell the API
>> that they want to wait for new messages.
>>
>> Here's an interesting question: Should the "messages" resource without
>> long-polling return the last X messages or should it only return new
>> messages (returning a 304 Not Modified response in the event that
>> there are no new messages since the last request).
>
>
> I think the messages call should return the set of available messages. =
=A0That
> may be a null set.
>
>
>> Should there be a
>> way to request the last X messages regardless, in case a client fails
>> to properly receive the response for some reason? I'm leaning towards
>> the "new messages only with a 304 response option".
>>
>
> I think having a separate history call would make sense. =A0It's going to=
 be
> more computational expensive to walk the message list for history (no, it=
's
> not going to bring the system to a grinding halt with our current workloa=
d,
> but it's conceptually different from "give me the latest stuff in the buc=
ket
> or hang out for a while if the bucket's empty")
>
>
>>
>> BTW, I'm not talking about using eTags here because my understanding
>> is that those are primarily about cache-control, which is not really
>> the point with streams. Maybe they would make sense on the resource
>> representations we have, and I'd like to discuss how to set that up
>> and whether Lift supports them (I'll keep my eyes open for this).
>>
>> Anyhow, that's my current thinking. Thoughts?
>>
>> > Lift's API is in fact stable and where there are occasional breaking
>> > changes, the compiler flags the issues (e.g., moving from Scala's Acto=
r
>> > implementation to Lift's Actor implementation). =A0In no case would th=
e
>> change
>> > of a Lift internal API make it impossible to support an existing HTTP =
API
>> > (or an existing AMQP or XMPP API for that matter.)
>> >
>> > But, more importantly, Xerox, Novell, and Four Square are among the hi=
gh
>> > profile companies that have built and deployed customer-facing
>> applications
>> > on Lift. =A0Breaking APIs so massively that web APIs no longer worked =
would
>> > cause these guys to come after me with a meat ax.
>>
>> Yup, I see that, and I'm not worried about Lift's abstractions
>> breaking the API when they are used correctly. I was just under the
>> mistaken impression that the current API was using the
>> front-end-oriented LiftCometActors. Sorry about that :-(
>>
>> Ethan
>>
>
>
>
> --
> Lift, the simply functional web framework http://liftweb.net
> Beginning Scala http://www.apress.com/book/view/1430219890
> Follow me: http://twitter.com/dpp
> Surf the harmonics
>