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

[Matthias Wessendorf]

On Fri, Sep 14, 2012 at 2:22 PM, Kris Borchers <kris at redhat.com> wrote:
>
> On Sep 13, 2012, at 10:25 PM, Douglas Campos <qmx at qmx.me> 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
>
>> - do we support batch operations? (as suggested by [1])
> +1
>
>> - logic name (/vehicles should be interpreted as "cars")
> -1 the client should ask for what they want from the server, not some alias
>
>> - read-only routes?
> not sure what you mean 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.
> +1 if you mean the server's endpoint is /signup and the client is configured to use it, not the alias type thing you were describing above
>

yeah - I thought, if the actual endpoint is /signup (instead of
/register), sure. Also... if there serve has an alias (not sure why),
I don't see why the client could not receive the /alias and go against
that one ..

-M


>>
>> 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 :)
> +1 http sessions as lowest common denominator and can add from there
>
>>
>> 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?
>>
>> (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)
> Pagination is important but could introduce some unwanted client/server coupling. We may be able to find some ways to avoid coupling and implement a best effort at covering the most popular pagination techniques in the clients but that would be it without introducing coupling. Technically, the JS lib could handle any form of pagination without introducing any coupling since arbitrary data can be passed to the server on any request so maybe really good documentation on that is the method to go with for JS and maybe the others. That would get a little more low level though instead of being able to just say, give me page 2 which I think would be preferred.
>
>>
>> [1]: http://blog.apigee.com/detail/restful_api_design_nouns_are_good_verbs_are_bad/
>> -- qmx
>>
>>
>> _______________________________________________
>> aerogear-dev mailing list
>> aerogear-dev at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev



-- 
Matthias Wessendorf

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