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

[Douglas Campos]

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]
- do we support batch operations? (as suggested by [1])
- logic name (/vehicles should be interpreted as "cars")
- 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.

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?

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

[1]: http://blog.apigee.com/detail/restful_api_design_nouns_are_good_verbs_are_bad/
-- qmx