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

[Matthias Wessendorf]

On Fri, Sep 14, 2012 at 5:25 AM, 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

this is a read for me too :)

>
> 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:
>

not sure how that is a _deep_ coupling between client and server; Of
course, the client needs to know the URI, but it should receive it via
a cfg param, e.g. an iOS example:

// NSURL object:
NSURL* projectsURL = [NSURL
URLWithString:@"http://todo-aerogear.rhcloud.com/todo-server"];

// create the 'todo' pipeline, which contains the 'projects' pipe:
AGPipeline* todo = [AGPipeline pipelineWithPipe:@"projects"
url:projectsURL type:@"REST"];

=> The endpoint URL here is
'http://todo-aerogear.rhcloud.com/todo-server/projects', which the
client API only knows since it has been passed in


> - always_plural? (/cars everywhere) [1]

+1

> - do we support batch operations? (as suggested by [1])

+1

> - logic name (/vehicles should be interpreted as "cars")

you mean an alias, not sure I get this

> - read-only routes?
>
> 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.
>

of course

> 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.
>

I like the rules from the apigee blog, and they feel 'natural' to me

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

Well, I can see that a GET against /cars is a PITA when it returns a
gazillion entries :)

-Matthias

> [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



-- 
Matthias Wessendorf

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