RE: Specifying operations for instances

On 3 Jul 2014 at 23:40, McBennett, Pat wrote:
> Markus Lanthaler wrote on June 18, 2014 9:51 PM:
>> Example a) might look like this:
>>   ApiDocumentation: ForumPost supportedOperation x, y, does *not*
>>      include DELETE
>> /posts/a operation z, *not* a DELETE
>>
>> No DELETE in the representation of /posts/a and the ApiDocumentation also
>> "doesn't tell me otherwise", i.e., also doesn't include a DELETE.
>> 
>> Example b) might look like this
>>   ApiDocumentation: ForumPost supportedOperation x, y, does *not*
>>      include DELETE
>> /posts/b operation x (again, *not* a DELETE)
>>
>> The representation of /posts/b includes some (x) but not all (y is missing)
>> operations know to be supported by instance of the class ForumPost.
>> 
>> Thus,
>>    /posts/a has the following operations: x, y, z
>>    /posts/b has the following operations: x, y
>>
>> Where do you see "the clear inconsistency" Pat?
> 
> (Sorry for the delay in replying - work and travel getting in the way!)  So yes, I still see an
> inconsistency. Let me try to illustrate reusing your examples.
> 
> From the original a) above '...would you consider the absence of the DELETE operation in
> the instance's representation a good enough clue for the client not to render a delete button?'
> - Markus: 'Yes...'

The "..." is very important here as I said [1]

  "Yes, with the caveat that the ApiDocumentation doesn't tell me otherwise."


> So I interpreted Tomasz's original description as saying that the following scenario existed:
> 
> c)
> ApiDocumentation: ForumPost supportedOperation x, y, *does* include DELETE
> /posts/a operation z, *not* a DELETE

This scenario of course exists but it means that the server clearly tells the client that /posts/a *supports* the DELETE operation.


> ...in which case Tomasz's UI would probably render a DELETE button for '/posts/a' (since
> the DELETE operation *is* present in the API documentation), *but* that button would be
> grayed out and disabled (since the DELETE operation *is not* present in the instance's
> representation). That's what I was agreeing with, and I thought you were saying 'Yes' to too.

Nope. There's no reason to gray it out and disable that button. If that would be the case, then associating operations to classes in an ApiDocumentation would be completely useless as you would have to repeat exactly the same representation in each "instance representation".


> But in b), you then stated that the '...the operations associated to the resource itself and the
> ones associated to its class are merged. After that, they are indistinguishable', which seemed
> to imply that we must always 'merge' the operations from the API documentation and the
> resource instance, which from my c) above would mean:
> 
> /posts/a operation z, x, y, DELETE (i.e. I must 'merge' all operations from the API doc and
> the resource instance.)

That's right and the whole idea behind it.


> And therefore Tomasz's UI should now render the DELETE button as *enabled* (as well as
> enabling operations for z, x and y of course,

Right


> when in fact the only operation '/posts/a' actually supports right now is 'z').

If that's the case, then the ApiDocumentation is lying in the sense that it is asserting false facts and should be fixed. 


> I'm pretty sure that wasn't your intended meaning. I think you probably meant 'additional
> operations appearing in the resource instance at runtime should be included (or considered
> 'enabled') by the client, even if they never appeared in the API documentation, whereas
> operations declared in the API documentation, but missing from the resource instance can
> be considered 'Unavailable (or 'disabled') at this time''. But anyway that's where I was
> seeing the inconsistency.

Nope, that was not was I meant and I hope this email clarifies this. What value would an operation declared in the API documentation have if it would have to be declared again in "resource instances" to be considered "available"?


Cheers,
Markus


[1] http://lists.w3.org/Archives/Public/public-hydra/2014Jun/0075.html



--
Markus Lanthaler
@markuslanthaler

Received on Monday, 7 July 2014 16:03:33 UTC