About the REST/ROA posts(no that isn't a word joke :)
Mathijs Kwik
I read through the blogposts about REST.
This is exactly the kind of discussion I like :)
I put together a braindump on this subject, being a mix of questions
that came up while reading the article and stuff I had in mind before.
It might be a bit hard to follow and partially off-topic, but I
thought I'd post it anyway.
Since I've been moving towards functional programming/data structures
lately, I really like the distributed hash view.
For the rest, I have to agree on the GET/PUT/DELETE/HEAD stuff, and
about post being the catchall action.
Thing is, what if we have 2 "custom" actions on a resource (so 1 post
action is not enough).
We might be able to figure out the intention by looking at the post
body (or mandating to put the custom action name inside the post
body), or we can use the URL (/myresource/special1,
/myresource/special2).
But since URLs are somewhat supposed to be resources (keys for the
hash), it's a bit strange to create a new "special" resource which
only accepts a custom method.
So it might be better to move the action-name to a param/query
(/myresource?special1) or (/myresource?action=special1)
What are everyone's opinions on those choices?
Playing around with document databases too, I came to realize they
feel a lot more natural for most stuff we want to model.
I noticed I started creating richer "objects" for resources, having
more structure (nesting, hashes, lists).
Mapping those back to relational stuff (especially on ActiveRecord)
required quite some before/after filters and storing stuff in
temporary instance variables.
Basically, it becomes pain, especially if more higher-level
validations(spanning multiple models) are involved.
Some patterns could be abstracted into mixins, but didn't really
belong in the model, making me think about conductors filling the gap
between resource-objects and models.
Anyway, I don't think I have to expand on why the way rails
couples(really, "forces" might be a better word) models and resources
is bad.
It very much makes you wanna keep your resources flat and only use
built-in nesting (which only maps to associations)
This leaves me with a bit of a question I want to get a clearer vision on.
I know the article wasn't really about the "objects" in the resource,
but since the social networking example touched on it briefly, I'll
bring it up anyway.
Seeing "friends" as a singular resource (1 list of friends) is OK with
me, did some singular list-shaped resources myself.
We can go 1 level "up" from this list:
I think it's ok to just put "friends" on a user resource, as a nested field.
In that case, adding a friend just means updating(PUTting the user-resource).
We can also go 1 level "down" from the list:
Let's consider a friendship being a full-blown resource(maybe you want
to record since when they are friends, or how they know each
other(school, work, sports)).
There's a bit of a problem with the URI. rails would just use
friendship-ids(which - in my opinion - is just the relational database
(internal representation) leaking through), but sure we can come up
with a better choice(like the friend's name).
Now, we have 3 ways of manipulating friends.
I personally feel still good about this, but maybe others can tell me
why this might be bad.
I do want to find a good restriction (rule of thumb) on this for
myself, because we can easily take this too far.
Now, since REST seems to have a strong focus towards hyperlinking
resources together, I can thinking of different representations of
those resources.
Not talking about them being html or xml or json or something, just
conceptually.
How do we feel about this:
A user resource for a person with some friends: the "friends" field is
a list of friend-names(maybe they should be links to that user, of to
the friendship-resource?).
A user resource for a person with lots of friends: the "friends" field
is just a link to the friends resource.
To a human, this makes lots of sense, but it might complicate things
for machines later on?
Also, having many resources representing the same functionality might
quickly cause having way to many resources around and ask for
automation.
On the other hand, it gives consumers of our resources a lot of flexibility.
One last thing that came to mind (a bit based on stuff I saw people
put in excel sheets that were supposed to be structured):
Should PUTting a resource take the payload literally? (as in, I GET
something, change some stuff, PUT it back)
Or are 'clever' things inside the document allowed?
like PUTting "*, john, kate, fred" inside the friends resource, the
star representing "everyone already in there"
Well, that's all for now, it's a bit late here and I don't want to
make a fool of myself just yet :)
I hope I still dropped some valid points for further discussion.
'night
Mathijs
Daniel Yoder
> action is not enough).
[...]
> But since URLs are somewhat supposed to be resources (keys for the
> hash), it's a bit strange to create a new "special" resource which
> only accepts a custom method.
> So it might be better to move the action-name to a param/query
> (/myresource?special1) or (/myresource?action=special1)
> What are everyone's opinions on those choices?
The query params are part of the URI.
I have no idea what the canonical right answer is here. I would expect
that the request headers or body would provide additional information
for the processing for that resource. So for example you might
provide, say, a JSON body with the processing instructions.
> Playing around with document databases too, I came to realize they
> feel a lot more natural for most stuff we want to model.
[...]
> This leaves me with a bit of a question I want to get a clearer
> vision on.
> I know the article wasn't really about the "objects" in the resource,
> but since the social networking example touched on it briefly, I'll
> bring it up anyway.
> Seeing "friends" as a singular resource (1 list of friends) is OK with
> me, did some singular list-shaped resources myself.
> We can go 1 level "up" from this list:
> I think it's ok to just put "friends" on a user resource, as a
> nested field.
> In that case, adding a friend just means updating(PUTting the user-
> resource).
You can certainly do that, but I don't think it would qualify as REST,
as defined by RF. OTOH, if you just POSTed that friend, no worries.
There is a draft standard (at least I think it is a draft standard)
for PATCH, also, which is intended to handle the partial update
scenario.
> There's a bit of a problem with the URI. rails would just use
> friendship-ids(which - in my opinion - is just the relational database
> (internal representation) leaking through), but sure we can come up
> with a better choice(like the friend's name).
You can use the IDs, but, yeah, it might be a bit brittle. Of course,
logically that URI (for a given friendship) provides no guarantees. If
you change it, you would just redirect old links, and clients should
be generally using linked data to get at it, precisely so it can
change over time, if necessary.
> Now, we have 3 ways of manipulating friends.
> I personally feel still good about this, but maybe others can tell me
> why this might be bad.
> I do want to find a good restriction (rule of thumb) on this for
> myself, because we can easily take this too far.
I think the rule of thumb is "stick to GET, PUT, and DELETE (and
possibly PATCH)" whenever possible. They have well-defined semantics.
Use POST when, for some reason (performance, complexity) you need to
go beyond those semantics. Every time you have to do that, you are
introducing additional points of coupling between your interface and
its clients. So you want to avoid it if possible.
The tricky part with doing a PUT on a friendship resource is where you
get the URI for the new friendship. I think you'd have to do a POST or
PATCH initially and then the friends list could just have the link to
the resource.
[...]
> A user resource for a person with some friends: the "friends" field is
> a list of friend-names(maybe they should be links to that user, of to
> the friendship-resource?).
Yes, they should be URIs, if at all possible.
> To a human, this makes lots of sense, but it might complicate things
> for machines later on?
How so? I think the point is to make it easier for machines. =)
> One last thing that came to mind (a bit based on stuff I saw people
> put in excel sheets that were supposed to be structured):
> Should PUTting a resource take the payload literally? (as in, I GET
> something, change some stuff, PUT it back)
> Or are 'clever' things inside the document allowed?
> like PUTting "*, john, kate, fred" inside the friends resource, the
> star representing "everyone already in there"
As long as the representation is a published format of some kind, and
as long as it describes the resource the URI refers in its entirety,
than I think, yes, it is fine. That said, what is interesting is that
you are describing PATCH, in effect, and have just reproduced the
entire controversy around it as well. Nicely done.
> Well, that's all for now, it's a bit late here and I don't want to
> make a fool of myself just yet :)
Ah, come on in! The water's fine!
Dan