Re: ISSUE-31: Are Operations violating REST's uniform interface constraint? (was: More Thoughts on Links and Operation Subclasses)

On Thu, Feb 6, 2014 at 12:29 PM, Markus Lanthaler
<markus.lanthaler@gmx.net> wrote:
>> On Wed, Feb 5, 2014 at 2:06 PM, Markus Lanthaler wrote:
>> > Great. So, before I close this issue I would like to get Mark's
>> > opinion (that's why I CCed you). Mark, do you agree with Ryan on
>> > this or do you think Operations do violate REST's uniform
>> > interface constraint?
>>
>> I believe they violate the constraint, yes.
>
> Let me ask a provocative question: Why do you think Operations violate the
> constraint whereas link relations, which further describe a potential GET
> request, don't?

That's a really interesting question, not provocative in the
slightest. But it's actually a very subtle difference between the two
approaches, as in theory, each could be used/misused in the same way.
The difference is in our expectations as developers and, concretely,
how we write our clients to react to the different kinds of
information available at design time and at run time. That would take
a lot of time to describe in a compelling way, I expect.

Luckily though, I can at least illustrate *part* of the difference
with a simple edge case that demonstrates a distinct loss of
visibility in the message exchange (commonly, a sign of a violation of
the uniform interface constraint).

Say we have a service which we describe with a custom hydra:Operation
called "Clear", which uses the HTTP DELETE method, but also expresses
that the target resource will create a new "empty" resource (of *it's*
choosing, so PUT isn't appropriate). This might be used on a wiki,
where you wouldn't expect that a resource return 404 or 410 after a
DELETE, but instead just show a blank page. A semantic wiki could do
something similar, returning an empty graph in its RDF representations
instead of 404/410.

So a client consuming a Hydra description and recognizing the "Clear"
operation would know things that, for example, an HTTP proxy wouldn't
know by only understanding the DELETE operation. It might choose, for
example, to dispense with any error checking for 4xx since it knows
that after a successful DELETE/Clear, that it will get back a blank
page. That is the loss of visibility I mentioned, and results from
extending the contract between client and server, rather than reusing
the existing one.

FWIW, using a predicate based approach, this could be done with a link
annotated with atom:edit or similar. There'd be no loss of visibility
because the client would have no additional expectations based on
previous interactions.

Mark.

Received on Wednesday, 12 February 2014 15:00:37 UTC