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

OK, I think we are making some progress now.. Let me try to split this
discussion into two threads. This one is about

  "Are Operations violating REST's uniform interface constraint?" - ISSUE-31

More about this inline below.

I'll start the second thread in a minute.


On Tuesday, February 04, 2014 2:11 AM, Ryan J. McDonough wrote:
> On Feb 3, 2014, at 3:19 PM, Markus Lanthaler <markus.lanthaler@gmx.net>
> wrote:
> 
> > On Friday, January 31, 2014 4:50 PM, Ryan J. McDonough wrote:
> >> On Jan 30, 2014, at 9:20 AM, Mark Baker <distobj@acm.org> wrote:
> >>
> >>> Our last discussion failed, but this discussion on Ryan's excellent
> >>> points seems to have drilled down to a bite sized point that I'll
> >>> offer a quick observation on...
> >>>
> >>> On Tue, Jan 28, 2014 at 7:45 AM, Markus Lanthaler wrote:
> >>>> Yeah, DELETE is very specific and it might look as if it doesn't
> >>>> have any value. There exist, however, APIs that archive resources
> >>>> that are being deleted. In such a case, I think it does make sense
> >>>> to qualify a DELETE with an ArchiveOperation or something similar.
> >>>> Basically the operation tells the client what kind of consequences
> >>>> it can expect if it invokes an operation.
> >>>
> >>> What you describe there is not REST. With REST, the client only knows
> >>> that a DELETE was performed upon receiving a 200 response, not that a
> >>> DELETE was performed along with some other stuff that is indicated
> >>> separately (either in-band in the message, or out-of-band via
> >>> information received in a prior interaction). *Just* DELETE, as
> >>> defined in the HTTP spec.
> >
> > Right. That's the contract. But AFAICT that doesn't mean that it is a
> > violation of any of REST's constraints to give a client more information
> > that it can use to choose which of the potential requests it might
> > wanna make.
> >
> > Do you disagree?
> 
> Yes. The draw of HTTP is the uniform interface. In between you and the
> origin server (i.e. the Hydra application) there could be multiple
> intermediaries that return to you something other than the specified
> hydra:statusCode or hydra:returns. The documentation is nice, but
> people tend to take it too literally.

Ryan, Mark, let's try to concentrate on Operation types in this thread and
ignore "returns"/"statusCodes" for the time being. Do you think qualifying a
potential HTTP request with an Operation type violates REST's uniform
interface constraint? If so, why? How is an operation type different to a
textual description above a form in an HTML page?

[...]

> >
> > IMO it doesn't matter whether a media type or a vocabulary a defines
> that.
> 
> Sure it does. If it makes the developer make false assumptions about
> what is being returned, it absolutely matters.

What I meant was does it matter where those expectations are codified?
What's the difference of them being in the media type (or in the usage of a
specific link relation in the context of a specific media type, yes I'm
thinking about AtomPub) vs. them being described in a vocabulary?


[...]

> >> Now, without a doubt, HTML forms don't do much to describe what the
> >> form does. HTML rely's on the fact that a Human can parse the text on
> >> the page in order to determine the controls function. In Hydra, we're
> >> trying to get at the machine parseable analog to descriptive text. I
> >
> > Exactly. The solution I chose was to type operations as I felt that's
the
> > simplest solution that a lot of people will understand instinctively.
How
> > would you describe it instead?
> 
> I agree that people will instinctively get this, but HTTP doesn't work
> this way. HTTP requests and have variable response types and Hydra is
> doing what WADL and Swagger do and suggest that there's a single, fixed
> response types.

Please let's try to not conflate Operation types and returns/statusCodes.
So, let me ask again: How would you design the "machine parseable analog to
descriptive text" in Hydra? Why do you think Operation types are
inappropriate? I'm actually not even sure whether you (Ryan or Mark) do but
hopefully this thread will help use to find that out.



--
Markus Lanthaler
@markuslanthaler

Received on Tuesday, 4 February 2014 14:54:44 UTC