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

[Glen Daniels]

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);

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