5:25 a.m.
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...
-- qmx
8:54 a.m.
On Fri, Sep 14, 2012 at 5:25 AM, Douglas Campos <qmx(a)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...
-- qmx
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)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
2:22 p.m.
On Sep 13, 2012, at 10:25 PM, Douglas Campos <qmx(a)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
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...
-- qmx
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
3:52 p.m.
On Fri, Sep 14, 2012 at 2:22 PM, Kris Borchers <kris(a)redhat.com> wrote:
On Sep 13, 2012, at 10:25 PM, Douglas Campos <qmx(a)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...
> -- qmx
>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)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
6:42 p.m.
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-applic...
http://tools.ietf.org/html/rfc5005
--Glen
10:12 p.m.
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-applic...
http://tools.ietf.org/html/rfc5005
--Glen
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org <javascript:;>
https://lists.jboss.org/mailman/listinfo/aerogear-dev
--
Sent from Gmail Mobile
10:32 p.m.
On Sep 14, 2012, at 5:12 PM, Matthias Wessendorf wrote:
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
yup, aliases is the right word
english is hard :)
-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-applic...
http://tools.ietf.org/html/rfc5005
--Glen
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
--
Sent from Gmail Mobile
_______________________________________________
aerogear-dev mailing list
aerogear-dev(a)lists.jboss.org
https://lists.jboss.org/mailman/listinfo/aerogear-dev
-- qmx
11:53 a.m.
On Fri, Sep 14, 2012 at 10:12 PM, Matthias Wessendorf <matzew(a)apache.org> wrote:
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?
Actually, looking at [1] I see that the "vehicles" is the URI - not a
logical name on the client :)
So... something like 'new Pipe("cars", Car.class);' works if the
server allows an 'alias' (e.g. /cars) for the /vehicles endpoint
(or the other way around).
Not sure how having server side aliases is a problem. I guess it's up
to the 'service provider' as long as the client API can read the
(working) endpoint URI to work against.
That said, not sure why one would actually introduce a lot of aliases
for a single endpoint...
-M
[1]
https://github.com/gdaniels/android-data/blob/master/android/src/org/aero...
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-applic...
> http://tools.ietf.org/html/rfc5005
>
> --Glen
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
--
Sent from Gmail Mobile
--
Matthias Wessendorf
blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf
2:14 p.m.
Hi Matthias,
On 9/15/12 5:53 AM, Matthias Wessendorf wrote:
On Fri, Sep 14, 2012 at 10:12 PM, Matthias Wessendorf
<matzew(a)apache.org> wrote:
> On Friday, September 14, 2012, Glen Daniels wrote:
>> On 9/13/12 11:25 PM, Douglas Campos wrote:
>>> - 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?
Actually, looking at [1] I see that the "vehicles" is the URI - not a
logical name on the client :)
Yup!
So... something like 'new Pipe("cars", Car.class);'
works if the
server allows an 'alias' (e.g. /cars) for the /vehicles endpoint
(or the other way around).
Not sure how having server side aliases is a problem. I guess it's up
to the 'service provider' as long as the client API can read the
(working) endpoint URI to work against.
That said, not sure why one would actually introduce a lot of aliases
for a single endpoint...
Agreed - it's not a problem at all, but neither do I think we need to
actually do anything about it for AeroGear.
--G
4233
days inactive
4234
days old
8 comments
4 participants
participants (4)
-
Douglas Campos -
Glen Daniels -
Kris Borchers -
Matthias Wessendorf