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

[Matthias Wessendorf]

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?


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 <javascript:;>
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>


-- 
Sent from Gmail Mobile
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20120914/1e639d4e/attachment.html