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

On Wednesday, February 12, 2014 4:00 PM, Mark Baker wrote:
> On Thu, Feb 6, 2014 at 12:29 PM, Markus Lanthaler 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.

OK.. so the server just deletes the content of a representation or replaces
it with something else; something the server chooses not the client. Like an
empty template e.g.


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

Yeah, even though here the knowledge would be quite limited (it knows that
he *likely* won't get a 404 if he GETs the resource immediately after)


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

Here you lose me. Why should it stop 4xx-error checking after a successful
DELETE/Clear? To make this crystal clear, are you saying

  - the client invokes the DELETE/Clear
  - checks the status code of the response

and *then* stops to check for 4xx errors? Why should it do so? What would it
do then if it tries to dereference such a resource and get a 404? Would it
break in a way it wouldn't otherwise?


> That is the loss of visibility I mentioned, and results from
> extending the contract between client and server, rather than reusing
> the existing one.

I understand in principle what you mean (the proxy doesn't know as much as
the client does) but can't see how that's a problem as long as you don't
violate the semantics of HTTP operations. On the other hand, since all
messages are self-descriptive and the ApiDocumentation is machine-readable,
even intermediaries are in the position to parse that "knowledge"--something
which is impossible with HTML forms e.g.


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

Why wouldn't it? I really see no difference between an xyz:clear link
relation and a Clear operation. If you talk about link relations, the client
*always* has "expectations based on previous interactions", namely the one
in which he got that link.

Taking AtomPub as example, a client has an expectation that a POST to a
collection URL results in a (media) resource being created. He has that
expectation due to a previous interaction (retrieval of the service
document). An intermediary lacks that knowledge. Is that also a violation of
the constraint then? So, whether I have a 

   <collection href="http://example.org/col" >
     ...
   </collection>

in an application/atomsvc+xml document or a 

  "@id": "http://example.org/col",
  "operation": {
    "@type": "CreateResourceOperation",
    "method": "POST"
  }

in a in an application/ld+json document doesn't make any difference IMO.


I'm sorry, I'm really trying to understand your concerns but apparently I
still don't.



--
Markus Lanthaler
@markuslanthaler

Received on Thursday, 13 February 2014 20:15:26 UTC