[aerogear-dev] Server Contracts and Thoughts about Server-Agnostic Clients

[Matthias Wessendorf]

On Fri, Sep 14, 2012 at 10:12 PM, Matthias Wessendorf <matzew at apache.org> wrote:
>
>
> On Friday, September 14, 2012, Glen Daniels wrote:
>>
>> On 9/13/12 11:25 PM, Douglas Campos wrote:
>> > Howdy!
>> >
>> > I was thinking on how to start this conversation on server contracts, so
>> > let's start with an example for a resource named "car" - all interactions
>> > are 'application/json'.
>> >
>> > We talked on irc about how to maintain the bare minimum that would give
>> > us full agnostic server backends, and I've tried to limit as CRUDL - CRUD +
>> > List without pagination :)
>> >
>> > C     POST            /cars
>> > R     GET             /car/1
>> > U     PUT             /car/1
>> > D     DELETE          /car/1
>> > L     GET             /cars
>> >
>> > Glen commented on irc that this would introduce coupling between the
>> > client and the server - but the point is that the endpoint style can and
>> > should be configurable in several levels:
>> >
>> > - always_plural? (/cars everywhere) [1]
>>
>> +1.  I don't think we should initially even care abut the above case,
>> but only support "/cars" and "/cars/1".
>>
>> > - do we support batch operations? (as suggested by [1])
>>
>> By "batch" do you mean PUT to "/cars" to bulk-update the whole
>> collection?  I don't think we need to do that initially either, as most
>> REST APIs I've seen don't support that.
>>
>> > - logic name (/vehicles should be interpreted as "cars")
>>
>> No need to do anything explicit about this, if I'm understanding you
>> correctly.  Taking a Java/Android example, if you want to play with
>> cars, you could just do:
>>
>> pipe = new Pipe("vehicles", Car.class);
>
>
>
> vehicles is a logical name on the client, for the /cars resource (due to the
> Car type), right?

Actually, looking at [1] I see that the "vehicles" is the URI - not a
logical name on the client :)

So... something like 'new Pipe("cars", Car.class);' works if the
server allows an 'alias' (e.g. /cars) for the /vehicles endpoint
(or the other way around).

Not sure how having server side aliases is a problem. I guess it's up
to the 'service provider' as long as the client API can read the
(working) endpoint URI to work against.

That said, not sure why one would actually introduce a lot of aliases
for a single endpoint...

-M

[1] https://github.com/gdaniels/android-data/blob/master/android/src/org/aerogear/android/Pipe.java#L41


> I tought he meant endpoint aliases
>
> -M
>
>>
>>
>> In other words, specifying the URL for a given collection's root is up
>> to the dev.
>>
>> > - read-only routes?
>>
>> Not sure what this means?  Certainly authorization is a factor here.
>>
>> > The point is, we can and should adapt to the most common scenarios - so
>> > an user should be able to use /signup instead of /register for auth
>> > endpoints - and there's what is a must for us IMO.
>>
>> ...yes, but that still assumes that you send the same piece of JSON to
>> your auth endpoint, right?  Or perhaps "username"/"password" form fields
>> - but of course some of those also need a "passwordConfirm" param... or
>> maybe a "confirmPassword" param... or OAuth... and that's when I think
>> you start getting into hairy stuff.
>>
>> > The user is using a <insert your technology here> server? if he supports
>> > http sessions we should be able to authenticate him, and here is where our
>> > challenge lies - being "inclusive" without making our APIs lame :)
>> >
>> > So, we need to figure out what is more common, and make this the default
>> > (or convention), while still allowing our users to choose different/weird
>> > conventions for their endpoints.
>> >
>> > Thoughts?
>>
>> Challenging.
>>
>> > (Before I forgot, Glen asked about pagination too, and I think this
>> > should be layered on top of this basics, as in this case there is no
>> > standard way to do it)
>>
>> Like security, there are a few best practices / common patterns here
>> too.  Examples:
>>
>> http://stackoverflow.com/questions/924472/paging-in-a-rest-collection
>>
>> http://stackoverflow.com/questions/776448/pagination-in-a-rest-web-application
>> http://tools.ietf.org/html/rfc5005
>>
>> --Glen
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
>
> --
> Sent from Gmail Mobile



-- 
Matthias Wessendorf

blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf